Apply Patch

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

1. You include { "type": "openrouter:apply_patch" } in your tools array when calling the Responses API.
2. Based on the conversation, the model decides a file needs to be created, updated, or deleted, and generates a V4A diff patch.
3. OpenRouter validates the patch syntax (correct line prefixes, valid markers, non-empty paths).
4. 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.
5. 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

1
const response = await fetch('https://openrouter.ai/api/v1/responses', {
2
  method: 'POST',
3
  headers: {
4
    Authorization: 'Bearer {{API_KEY_REF}}',
5
    'Content-Type': 'application/json',
6
  },
7
  body: JSON.stringify({
8
    model: '{{MODEL}}',
9
    input: 'Create a hello.py file that prints "Hello, world!"',
10
    tools: [
11
      { type: 'openrouter:apply_patch' }
12
    ]
13
  }),
14
});
15
16
const data = await response.json();
17
// The response contains an apply_patch_call output item
18
// with the operation (create_file, update_file, or delete_file)
19
console.log(data.output);

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 +:

1
{
2
  "type": "apply_patch_call",
3
  "call_id": "call_abc123",
4
  "status": "completed",
5
  "operation": {
6
    "type": "create_file",
7
    "path": "/src/hello.py",
8
    "diff": "+print(\"Hello, world!\")\n"
9
  }
10
}

update_file

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

1
{
2
  "type": "apply_patch_call",
3
  "call_id": "call_def456",
4
  "status": "completed",
5
  "operation": {
6
    "type": "update_file",
7
    "path": "/src/main.ts",
8
    "diff": "@@ function main() {\n-  console.log(\"old\");\n+  console.log(\"new\");\n }"
9
  }
10
}

delete_file

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

1
{
2
  "type": "apply_patch_call",
3
  "call_id": "call_ghi789",
4
  "status": "completed",
5
  "operation": {
6
    "type": "delete_file",
7
    "path": "/src/deprecated.ts"
8
  }
9
}

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:

1
{
2
  "model": "openai/codex-mini",
3
  "input": [
4
    {
5
      "type": "apply_patch_call_output",
6
      "call_id": "call_abc123",
7
      "status": "completed",
8
      "output": "Applied patch to /src/hello.py"
9
    }
10
  ],
11
  "tools": [
12
    { "type": "openrouter:apply_patch" }
13
  ]
14
}

Configuration

The apply patch tool accepts an optional engine parameter:

1
{
2
  "type": "openrouter:apply_patch",
3
  "parameters": {
4
    "engine": "auto"
5
  }
6
}

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