Modify Request
modify_requestUpdate a Bruno API request file by merging only the fields you provide, preserving all others. Edit URLs, headers, auth, body, scripts, assertions, or settings; supports rename, file uploads, and multipart data in one call.
Instructions
Update an existing Bruno request file with partial-merge semantics. Only provided fields are updated; all other fields are preserved. Supports multipart/form-data with file uploads and per-part contentType. Inline scripts REPLACE the existing script of the same type by default (idempotent — repeated calls do not accumulate duplicate blocks); pass scriptMode:"append" to concatenate instead. Use remove_script to clear a script entirely. RENAMING: name and filename are independent, as they are in Bruno itself — name changes the request's name inside the file and filename moves the file. Pass both to keep them in step, and read the new path back from the response.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | ||
| auth | No | ||
| body | No | ||
| grpc | No | gRPC-only fields. Applies to kind "grpc" and is refused otherwise. Headers given for a gRPC request are written as metadata, which is that transport's only header surface. | |
| name | No | The request's name inside the file. Does NOT rename the file — pass filename for that. | |
| vars | No | ||
| query | No | ||
| assert | No | Replaces the whole assert block. Omit to leave existing assertions untouched. | |
| method | No | ||
| headers | No | ||
| scripts | No | Inline scripts to persist with the request. Keys: pre-request, post-response, tests (aliases before-request/after-response accepted). Avoids a separate add_test_script call. IMPORTANT for tests/post-response: only assertions inside a test() block are reported. Write test("status is 200", function() { expect(res.getStatus()).to.equal(200); }); — a bare expect() at the top level still runs, but a passing one records nothing, so run_collection reports "tests": [] and the request looks green with no assertions. Available in scripts: res.getStatus()/getStatusText()/getHeader(name)/getHeaders()/getBody()/getResponseTime(), res.getStopReason()/getCloseCode()/getSessionTruncated() on a websocket request, which report the same session outcome the result does (all null or false on an HTTP response, which has no session), bru.setVar(name, value)/getVar(name)/getEnvVar(name)/hasEnvVar(name), and expect(actual) with .to.equal/.contain/.include, .to.have.property/.lengthOf, .to.be.a/.an, .to.be.above/.below/.at.least/.at.most (aliases .gt/.lt/.gte/.lte/.greaterThan/.lessThan), .to.be.within(min, max), .to.be.oneOf([...]), .to.match(/re/), .to.startWith/.endWith, .to.be.true/.false/.null/.undefined/.empty/.json,and .to.not.* negations. VARIABLES: bru.getVar(name) resolves environment and collection variables as well as anything a script set, so an environment variable needs no shadow copy to be readable. bru.getEnvVar(name) is narrower on purpose: it reads the environment layer only, so a runtime variable of the same name does not shadow it. There is no setEnvVar — nothing here writes an environment file. RETURN TYPE: res.getBody() returns the response already parsed into a JS object/array when the Content-Type is application/json or a +json type (raw text otherwise). Access fields directly — res.getBody().field — and do NOT JSON.parse() it, which throws SyntaxError: "[object Object]" is not valid JSON. | |
| filePath | Yes | Absolute path to the .yml or .bru request file to modify. Get from list_requests or get_collection_stats. | |
| filename | No | Renames the file, keeping it in its own folder. Basename only, no path separators. The extension is optional and must match the collection's format if given, since a collection carries one format only. Refused if another file of that name already exists. The new path comes back in the response; use it as filePath from then on, because the old one is gone. | |
| settings | No | Request-level settings: transport behaviour (timeouts, redirects, URL encoding), not payload. What reaches the file depends on the dialect, because Bruno's own two writers differ: a .yml request always carries a fully resolved settings block whether or not you pass one, while a .bru request carries only what you supply. On modify_request the fields are merged individually over the existing block, so setting one does not clear the rest. Note the encodeUrl field: in .bru, creating a block at all changes the URL-encoding default. | |
| websocket | No | WebSocket-only fields. Applies to kind "websocket" and is refused otherwise. | |
| pathParams | No | Replaces the declared path parameters; query parameters are left alone. | |
| scriptMode | No | How to write the scripts field. "replace" (default) overwrites the existing script of each provided type, so calling modify_request repeatedly is idempotent. "append" concatenates onto the existing script, which accumulates blocks across calls. Each script type has its own slot in both .bru and .yml, so replacing one leaves the others untouched. One exception on .yml: supplying post-response and tests together in a single call still merges both into the after-response slot, so write the tests script in its own call to keep it in the tests slot. | replace |