---
title: "Write a file (path in body, utf8 or base64)"
method: POST
path: "/preview/nodes/{name}/files"
tags: ["nodes"]
---

# Write a file (path in body, utf8 or base64)

`POST /preview/nodes/{name}/files`

## Request

- Base URL: `https://autoresearch.sfcompute.com`
- URL: `https://autoresearch.sfcompute.com/preview/nodes/{name}/files`
- Auth: HTTP bearer

Write a small file onto a node: configs, entry scripts, calibration sets: the heredoc pattern as a real tool (no shell quoting, binary via encoding:"base64", executable:true for mode 0755). Returns {path, bytes_written, sha256, sha256_verified}; parents are created and an existing file is replaced atomically. sha256 is the digest of the content, and the file is hashed AGAIN on the node before it is moved into place (a mismatch refuses the write), so the receipt is a receipt for the bytes on the disk - hash your payload locally and compare, and a base64 blob that got mangled on the way in is caught by one string comparison instead of a debugging session (sha256_verified:false means the image has no sha256sum, so the file was checked by length alone). The content never rides a command line, so nothing of it is recorded. NOT for secrets: pass those as run_command's env (this writes plaintext to the node's disk); NOT for datasets or weights: pull those from inside the node (run_command: curl / git clone / huggingface-cli download). Getting results OUT: export_file returns a download URL, or push from inside the node (huggingface-cli upload, aws s3 cp, git push) before stopping it. Calling this on a stopped node wakes it, exactly like run_command (same queued/waking answers) - and THE WRITE DOES NOT HAPPEN on those answers: there is no pending-write queue, the content is not stored anywhere, and the answer says so (written:false). Re-send it once the node is running; to push several files, wake the node, then hold_node, then write, so the idle window cannot close between them. Files under ~ survive stop_node and wake. A wake this opens bills to the node's mission, like any other work on it. The answer's timing_ms (server: our whole handling; exec: the node leg) shows a write lands in well under a second; a slow call spent the rest in your client producing the content, so send text as utf8.

## Path parameters

- `name` string, required: Node name (from `list_nodes`).

## Query parameters

- `workspace` string

## Request body

- object
  - `content` string, required: The file content. UTF-8 text as-is; for binary (or awkward) bytes pass base64 and set encoding:"base64".
  - `encoding` string, nullable: "utf8" (default) or "base64".
  - `executable` boolean, nullable: true = mode 0755 (an entry script); default 0644.
  - `path` string, required: Destination path: absolute, or relative to the home directory (/home/dev). Parent directories are created; an existing file is replaced atomically.

## Response `200`

The capability's JSON result.

- Result: The capability's result: the same object the MCP tool returns as structuredContent. Resources carry an `object` type discriminator and an immutable id; money is integer micro-dollars in `*_usd_micros` fields.
  - `object` string: The resource type, when the result is one resource.

## Other responses

- `400`: Malformed request: bad JSON, a parameter that does not parse, or a value outside its range. Code `invalid`.
- `401`: No bearer token, or one this API cannot verify. Code `unauthenticated`.
- `403`: Authenticated, but the token's scopes or the account's role do not reach this operation. The message names the scope word to request. Code `forbidden`.
- `404`: No such route. Code `not_found`; the body names the OpenAPI document.
- `422`: A well-formed request the platform declined: no such node, a cap reached, a state that forbids the move. The message says which, and what to do instead. Code `refused`.
- `429`: Over this door's per-customer budget. Wait `Retry-After` seconds. Code `rate_limited`.
- `500`: Our fault. Retry; if it persists, quote the request-id. Code `internal`.
- `503`: The node changed state under every pass this call made - a wake, a stop, or a container exit landing mid-call. Nothing ran and nothing was billed; the same call works shortly. Wait `Retry-After` seconds and repeat it. Code `settling`.

---

[API](https://skmtc.dev/givemeanode/apis/autoresearch-customer-api.md) · [All operations](https://skmtc.dev/givemeanode/apis/autoresearch-customer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/givemeanode/apis/autoresearch-customer-api/revisions/f88dcb70ac6c?raw)