project_patch
Edit / change / update / modify / fix / tweak files in a deployed project — edit one or several deployed files in place with a find/replace, an ordered edits array of many find/replaces across files, a full-file rewrite, or a files map of several full-file writes in one atomic patch. Suited to visual-editor iteration and any quick code change. Unchanged files are preserved; only what you send is touched. Static changes reach production in ~1 second; function changes in 2–4 seconds.
For an existing project this touches only the files sent; project_deploy replaces the static file tree, so unchanged static files must be sent again. project_deploy is for the first deploy of a brand-new project.
The source comes from project_export. Its active_release_id is the base_release_id of the patch, including on dry runs. This required release anchor identifies the exact source you edited; base_version is an additional optional conflict check.
Three modes — same tool.
1. Find / replace (token-optimal, preferred for small edits): pass path + find + replace. The platform reads the current file, replaces every occurrence of find with replace, and writes it back. ~200 bytes on the wire instead of re-sending the whole file.
{ "project_id": "my-saas", "base_release_id": "<active_release_id from project_export>", "path": "index.html", "find": "<h1>Pricing</h1>", "replace": "<h1>Plans & pricing</h1>" }If find doesn't match the file, you get a 400 FIND_NOT_FOUND with a head/tail snippet. When a sufficiently similar region exists, data.closest_match also includes its offset, text and 0–1 confidence; unrelated text may have no close match. A corrected patch uses the exact text from a current project_export and that export's release anchor.
2. Ordered edits (many small changes in one patch): pass edits, an array of { "path", "find", "replace", "expect"? }, instead of top-level path/find/replace. Edits apply in order to the source of base_release_id (a later edit to the same file sees the earlier ones), across any number of files, and publish as ONE patch. If any edit does not match, nothing is published: the error is FIND_NOT_FOUND with zero-based data.edit_index. expect: n requires exactly n non-overlapping matches, else FIND_COUNT_MISMATCH with data.edit_index, data.path, data.expected and data.actual. At most 200 edits per call. A path is edited, written whole (files), or deleted (delete_files) in one patch, never two of these; other paths combine freely.
{ "project_id": "my-saas", "base_release_id": "<active_release_id from project_export>", "edits": [
{ "path": "src/App.tsx", "find": "const TITLE = 'Old'", "replace": "const TITLE = 'New'", "expect": 1 },
{ "path": "src/App.tsx", "find": "<Footer />", "replace": "<Footer year={2026} />" },
{ "path": "styles.css", "find": "color: red", "replace": "color: teal" }
] }Unified diffs are not a patch format: ordered exact replacements plus whole-file files writes cover the same changes without a second parser. Whole local trees deploy with somewhere deploy; somewhere call project_patch --file args.json sends a large argument object from a file.
3. Full content (rewriting the file): pass path + content. The new bytes replace the file entirely.
{ "project_id": "my-saas", "base_release_id": "<active_release_id from project_export>", "path": "styles.css", "content": "body { background: black }" }Path auto-routes: api/*, _lib/*, and root [id].ts paths go to functions; everything else (HTML, CSS, SVG, JSON, etc.) to static. Binary assets (images, fonts) use the matching binary surface — content and find/replace do not carry raw bytes.
Delete: delete_files is an array of paths. Works for static files and functions; missing paths are silently ignored. A rename or atomic replace combines one path + content write (or the one-entry files alias) with delete_files in the same call: the new file and removals publish as one patch transaction.
Conflict check (optional, recommended for shared projects): pass base_version from your last deploy/export response. If another deployer landed changes since, returns 409 STALE_BASE with data.changed_files, data.last_change_source, and data.last_change_at instead of overwriting. On STALE_BASE, project_diff_versions shows the change, and force:true overwrites the remote changes. The older expected_version strict CAS still works and returns VERSION_CONFLICT when the production version differs.
Preview first (optional): pass dry_run: true to get a per-file unified diff of what the patch WOULD change (data.diffs), plus added/modified/removed lists — nothing is written and the version doesn't change. The same call without dry_run applies it.
Safety net — what IS and is NOT checked. A patch that touches page-rendering files (HTML/JS/CSS) is blank-page health-checked after it goes live: if it blanked a previously-rendering page, the patch is automatically rolled back and you get a 400 DEPLOY_BLANK_PAGE with data.rolled_back. Pages that were already blank before the patch are never blocked.
A function-only patch (api/*, _lib/*, root [id].ts) is NOT blank-page-checked, and it does NOT get "the same protection as a full deploy." After a function patch the response carries a best-effort function_health field — { checked, status, ok } from one GET of a patched route. function_health.ok === false means the route returned a 5xx (e.g. a missing import → 500): your edit shipped but is broken in production. If function_health.checked === false the route couldn't be probed (no concrete route, browser unavailable) — it was NOT verified, so confirm it yourself. A clean build is NOT a working function; only function_health.ok === true (or your own request to the route) confirms it runs.
For a risky edit, dry_run:true and project_check come first, then one patch, verified on the public production URL. project_rollback restores the previous production version if needed.
Patches reach production immediately at https://{subdomain}.somewhere.site. The success response includes the new version, a next_step, function_errors (build failures) and, for function patches, function_health (runtime 5xx). Preview is advanced and must not be selected unless the user explicitly says the account is enabled.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"project_id": "<project_id>"
},
"name": "project_patch"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| find | No | Find/replace mode exact substring, paired with `path` and `replace`. All occurrences are replaced. Mutually exclusive with `content`. | |
| path | No | File path relative to project root (e.g. "api/hello.ts" or "index.html"). Required for both content and find/replace modes. | |
| edits | No | Ordered find/replace edits across one or more files, applied in order to the base_release_id source and published as one patch. Any edit that does not match fails the whole patch (FIND_NOT_FOUND with data.edit_index) and nothing is published. Exclusive with top-level path/find/replace/content; a path in edits may not also appear in files or delete_files. | |
| files | No | Full-file content writes as a {"path": "content"} map or an array of {path, content} items. One entry is the same as path+content; several entries are written together in one atomic patch, anchored to base_release_id, and every unlisted file is kept. Paths under api/, _lib/ and root [param] routes go to functions, everything else to static files, exactly as a single path is routed. May accompany delete_files in the same transaction. Find/replace uses top-level path+find+replace, not files items. | |
| force | No | Bypasses a STALE_BASE refusal and overwrites the remote changes it reported; project_diff_versions lists those changes. | |
| content | No | Full file content paired with `path`; it replaces the file entirely. `find` and `replace` provide the smaller-edit alternative. | |
| dry_run | No | Non-writing preview that returns per-file unified diffs plus added, modified, and removed lists. The version stays unchanged; a subsequent call without dry_run applies the patch. | |
| message | No | Optional user-supplied note for this version (max 200 characters). Required with note_version. | |
| preview | No | Advanced `somewhere preview` flag requiring hosted preview access for signed-in accounts on every plan; otherwise CLOUD_DEV_NOT_ENABLED is returned before resource creation. False (default) patches production. | |
| replace | No | Find/replace substitution paired with `path` and `find`. | |
| draft_id | No | Alias for preview_session_id. | |
| project_id | Yes | Project ID (UUID), subdomain, or slug — resolved server-side, no UUID lookup needed. 'default' also works when the account has exactly one project; multi-project accounts must name one (the error lists them). | |
| base_version | No | Optional stale-base version from the preceding deploy or export response. A 409 STALE_BASE indicates a remote change and requires reviewing project_diff_versions before a forced retry. | |
| delete_files | No | Paths to remove. Works for static files and functions. Paths not present are ignored. | |
| note_version | No | Change the note on this version. Send only project_id, note_version and message. | |
| base_release_id | No | Required for a project with a production release. It is the `active_release_id` from the same project read or export that supplied the edited source. A missing base fails closed; a stale base returns STALE_RELEASE_BASE without applying the patch. | |
| expected_version | No | Optional optimistic-concurrency version from the preceding deploy or patch response. A concurrent project change returns 409 VERSION_CONFLICT with `data.current_version` instead of overwriting. | |
| draft_operation_id | No | Alias for preview_operation_id. | |
| preview_session_id | No | Stable editing-session id for this preview lineage. Required with preview:true. | |
| expected_preview_id | No | Exact current preview id, or null for the first preview. | |
| preview_operation_id | No | Stable idempotency id for this exact preview build/retry. | |
| expected_candidate_release_id | No | Alias for expected_preview_id. |