Read and write files

Endpoint

GET /v1/disks/{disk}/files/{path}
PUT /v1/disks/{disk}/files/{path}
POST /v1/disks/{disk}/files/{path}
DELETE /v1/disks/{disk}/files/{path}

Path parameter	Meaning
`disk`	Named disk. See name rules.
`path`	File path relative to `/`; may contain `/` separators.

Read a file

curl --fail-with-body "https://api.wabe.sh/v1/disks/demo/files/hello.txt" \
  -H "Authorization: Bearer YOUR_PROJECT_API_KEY" \
  --output ./hello.txt

Response: 200, Content-Type: application/octet-stream, body containing the exact file bytes. File length can exceed the JS heap or KV value limit when the client consumes the response as a stream. The current endpoint has no byte-range API.

Replace a file

printf 'Hello wabe Disk\n' | curl --fail-with-body \
  -X PUT "https://api.wabe.sh/v1/disks/demo/files/hello.txt" \
  -H "Authorization: Bearer YOUR_PROJECT_API_KEY" \
  --data-binary @-

{"bytes":16,"metadata":{"version":2,"object_id":"00000000-0000-4000-8000-000000000001","version_id":"00000000-0000-4000-8000-000000000002","branch_id":"00000000-0000-4000-8000-000000000003","revision":1,"first_edit_at_ms":1792083906000,"last_edit_at_ms":1792083906000,"mode":33188,"kind":{"File":{"content_root":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","size":16,"chunk_bytes":65536}}}}

Generated identifiers and timestamps vary. metadata describes the state published by this write.

bytes is the number of bytes accepted for the replacement. The parent directory must exist. A file is published only after its upload completes; an upload cancelled before its input completes retains its old version. Once staging completes, publication can finish after disconnect. Concurrent replacements use the last published version. Existing readers can finish an older version.

Write acknowledgement follows the server’s durability mode. A successful buffered PUT does not confirm persistent storage.

Append and remove

POST streams an append, creating the file if its parent exists. It returns the appended byte count and published metadata. Concurrent appends each append at current EOF. A retry can duplicate bytes. DELETE removes a file or empty directory and returns 204.

All file operations accept one optional branch, commit or label selector; omitted selection uses live main. PUT/POST accept optional expected_id and expected_revision together. See versioning.

Errors

Status	Scenario
`400`	Invalid disk/path, traversal above `/`, or a directory supplied as a file.
`403`	A write to a historical view.
`409`	Stale expected version or nonempty directory.
`401`	Missing or incorrect server key.
`404`	Missing file on GET, or missing parent directory on PUT.
`500`	Storage or I/O failure.

Use directory listing to inspect paths. Create and remove directories through exec or the JS filesystem API.