How to Serve Fresh Fastio Assets After an Upload

When you ship a new stylesheet, image, or agent-generated report, the next reader should receive the new bytes. Fastio keeps a stable node_id for that file. A same-name upload into the same folder overwrites the current content, stores the previous bytes as a recoverable version, and leaves every stored link pointing at the same file. Do not delete-then-re-upload.

Treat "make this live" as a write followed by a read. Download the current bytes with GET /current/workspace/{workspace_id}/storage/{node_id}/read/. Request a preview with GET /current/workspace/{workspace_id}/storage/{node_id}/preview/{preview_type}/read/. Valid preview_type values are thumbnail, image, mp4, hlsstream, audio, pdf, spreadsheet, and bin. Request a transform with GET /current/workspace/{workspace_id}/storage/{node_id}/transform/{transform_name}/read/. Multi-file previews such as HLS return 307 Temporary Redirect to a sub-file endpoint.

Agent integrations should use the MCP server rather than raw HTTP. Streamable HTTP is https://mcp.fast.io/mcp (or https://mcp.fast.io/mcp/key with a Bearer header). Legacy SSE is https://mcp.fast.io/sse. Named mode exposes 19 tools, including upload, storage, find, ai, and event. The storage tool (list, search, move, copy, delete, details, version-list, version-restore) requires profile_type set to workspace or share. Ripley, the built-in RAG agent, answers questions about the new file through the ai tool with action ask.

Helpful references: Fastio Workspaces, Fastio AI, and storage for agents.

How widely you rewrite files changes blast radius and origin load. Prefer a single node_id when you know which asset changed. File details, a preview read, a transform read, or a version restore all name one object. Every other file in the workspace keeps serving its current bytes.

When you only know a filename, search first. GET /current/workspace/{workspace_id}/storage/search/ accepts search_in=filename|content|both (default both) and name_match=auto|exact|prefix|contains|glob. Use name_match=exact or prefix when the name is known. Use glob only when you truly need a pattern. Then act on the returned nodes one at a time: overwrite, restore, or read.

Folder-wide work is a list plus a loop. GET /current/workspace/{workspace_id}/storage/{parent_id}/list/ is cursor-based. Query params are sort_by=name|updated|created|type (default name), sort_dir=asc|desc (default asc), page_size=100|250|500 (default 100), and cursor. The response carries pagination.has_more, pagination.next_cursor, and pagination.page_size. Rely on has_more and next_cursor. A page can be short while has_more is true. Listing a large folder and rewriting every child is the expensive path. Reserve that for a full rebuild.

A single-node read, preview, or restore is the precise operation. Exact node_id work keeps the rest of the workspace serving existing bytes.

To publish a new version of an asset, upload the same name into the same folder, then read the current preview or bytes. Create an API key in Settings > Devices & Agents > API Keys, or with POST /current/user/auth/key/. Every authenticated call uses Authorization: Bearer {api_key} against https://api.fast.io/current/. Keep the trailing slashes. Workspace IDs and node IDs are 19-digit numeric strings.

For agents, call MCP upload, then MCP storage with action details or version-list (profile_type must be workspace or share):

{"jsonrpc":"2.0","id":1,"method":"tools/call",
 "params":{"name":"upload","arguments":{"action":"web-import","url":"https://example.com/report.pdf",
 "profile_type":"workspace","profile_id":"1234567890123456789"}}}

A same-name REST overwrite for a small file uses multipart form data:

curl -X POST "https://api.fast.io/current/upload/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "name=app.js" \
  -F "size=1048576" \
  -F "action=create" \
  -F "instance_id=1234567890123456789" \
  -F "folder_id=root" \
  -F "chunk=@app.js"

A successful small upload returns HTTP 201:

{"result":true,"id":"<upload_id>","new_file_id":"<node_id>"}

new_file_id is the stable node_id. Read a preview of the current file:

curl -X GET "https://api.fast.io/current/workspace/{workspace_id}/storage/{node_id}/preview/image/read/" \
  -H "Authorization: Bearer YOUR_API_KEY"

Swap image for thumbnail, mp4, hlsstream, audio, pdf, spreadsheet, or bin to match the asset. List history with GET /current/workspace/{workspace_id}/storage/{node_id}/versions/. Restore a prior snapshot with POST /current/workspace/{workspace_id}/storage/{node_id}/restore-version/. Most POST bodies are application/x-www-form-urlencoded. Uploads are multipart/form-data.

Manual republishing creates friction. After a successful build, the pipeline should upload changed artifacts into the workspace folder that already holds them. Same name, same folder, stable node_id. Parse the Webpack or Vite manifest, then upload each file that received a new hash. A new hashed filename is a new file. Replacing app.js is a same-name overwrite.

Small files (up to 200, each 4MB or less) can go through POST /current/upload/batch/. Larger files use a session on POST /current/upload/ (same form, no chunk), then POST /current/upload/{id}/chunk/?order=N&size=N, POST /current/upload/{id}/complete/, and GET /current/upload/{id}/details/?wait=60.

Confirm the write before the next stage. GET /current/workspace/{workspace_id}/storage/{node_id}/details/ returns the current file. GET /current/workspace/{workspace_id}/storage/{node_id}/versions/ lists recoverable history. Long-poll GET /current/activity/poll/{entityId}?wait=95&lastactivity={timestamp}, or search the audit log with GET /current/events/search/.

Headless agents in CI can attach MCP at https://mcp.fast.io/mcp and use code-mode tools (auth, upload, search, execute, room, how-to). The execute tool sends a structured method/path/body/params call against the REST API. You can test the same scripts in an isolated staging workspace, then point instance_id at production once the overwrite and the follow-up preview read succeed. OpenClaw setups can follow the same loop from the OpenClaw storage guide.

Give Your AI Agents Persistent Storage

Use 19 consolidated MCP tools to upload, version, and read workspace files from CI or agents. Built for serving the latest preview after every overwrite.

Try the MCP Server

Related pages often share one source file. Put those files in a folder, or extract structured metadata, rather than tracking a parallel index of dependent URLs.

Create a folder with POST /current/workspace/{workspace_id}/storage/{parent_id}/createfolder/. List its children with GET /current/workspace/{workspace_id}/storage/{parent_id}/list/. Search filenames or contents with GET /current/workspace/{workspace_id}/storage/search/. Search extracted fields with GET /current/workspace/{workspace_id}/metadata/search/. Define an extraction template with POST /current/workspace/{workspace_id}/metadata/templates/, then run POST /current/workspace/{workspace_id}/storage/{node_id}/metadata/extract/ on the file that just changed.

When a shared image or document changes, overwrite that node_id. Any later read, preview, or transform of that node returns the new bytes. Sibling pages that embed the same node_id pick up the new file on the next request. If the write looks wrong, restore the prior snapshot on the same node and leave every embed in place.

Agents group this work with MCP find (unified search across a workspace or share) and MCP storage (list, search, details, version-restore). Ripley can summarize the new file through ai with action ask once the overwrite lands.

As pipelines upload more artifacts, they share the same Fastio API limits as every other tenant. HTTP 429 with error code 1671 means the caller is rate limited. Wait until the x-ve-limit-expires header, then retry the same request.

Batching small writes reduces the number of calls. POST /current/upload/batch/ accepts up to 200 files, each 4MB or less. Prefer one batch over dozens of individual small uploads when the manifest is a pile of images or compiled chunks. Large binaries still use the chunked upload session on /current/upload/.

MCP callers can ask upload for action limits before a burst, then batch or web-import for the files themselves. If a 429 still arrives, pause until x-ve-limit-expires and send the same call again. Other documented error codes you may see on a bad request are 1605 Invalid Input, 1609 Not Found, 1650 Auth Invalid, 1680 Access Denied, 1685 Feature Limit, and 1654 Internal Error.

After the writes settle, synchronize downstream jobs from the activity log rather than a timer. GET /current/events/search/ and GET /current/activity/poll/{entityId}?wait=95&lastactivity={timestamp} are the audit trail. The MCP event tool covers the same activity log for agents.

After an overwrite, confirm the new version is the one readers will receive. A 201 from POST /current/upload/ tells you the session finished. It does not replace a follow-up read.

Check file details with GET /current/workspace/{workspace_id}/storage/{node_id}/details/. List versions with GET /current/workspace/{workspace_id}/storage/{node_id}/versions/. Then request the current bytes or a preview:

curl -X GET "https://api.fast.io/current/workspace/{workspace_id}/storage/{node_id}/preview/thumbnail/read/" \
  -H "Authorization: Bearer YOUR_API_KEY"

For video, use preview/mp4/read/ or preview/hlsstream/read/. HLS and other multi-file previews return 307 Temporary Redirect to a sub-file endpoint. Follow that Location in the player or in the next pipeline step. For a raw copy of the file, use GET /current/workspace/{workspace_id}/storage/{node_id}/read/.

Automated scripts should assert that details and versions return successfully, then that the preview or read responds. Agents on MCP call storage with action details or version-list (profile_type is workspace or share). If the latest write fails those checks, restore the prior snapshot with POST /current/workspace/{workspace_id}/storage/{node_id}/restore-version/ or MCP storage action version-restore.