# How to Serve Fresh Fastio Assets After an Upload

After a same-name upload, Fastio overwrites the file in place, keeps the prior bytes as a recoverable version, and leaves the node_id stable. Agents and CI jobs then read the current file, a preview, or a transform so clients receive the latest asset. This guide covers upload, version list and restore, preview and transform reads, the MCP storage tools, and rate-limit handling.

Source: https://fast.io/resources/fastio-cdn-cache-invalidation-api/
Last reviewed: 2026-08-13

## What to Check Before Overwriting a Fastio File via API

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 a consolidated MCP toolset, 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](/product/workspaces/), [Fastio AI](/product/ai/), and [storage for agents](/storage-for-agents/).

## Single Node Overwrite vs Folder-Wide Rewrites

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.

## How to Overwrite a File and Request a Preview

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`):

```json
{"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:

```bash
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:

```json
{"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:

```bash
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`.

## Integrating Overwrites into CI/CD Pipelines

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](/storage-for-openclaw/).

## Group Related Files with Folders and Metadata

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.

## Handling Rate Limits and API Synchronization

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.

## Validate Overwrite Success with Versions and Previews

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:

```bash
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`.

## Frequently asked questions

### How do I serve a new version of a Fastio file?

Upload the same filename into the same folder so the node_id stays stable and the previous bytes remain a recoverable version. Then read the current file with GET /current/workspace/{workspace_id}/storage/{node_id}/read/, or request a preview (thumbnail, image, mp4, hlsstream, audio, pdf, spreadsheet, or bin) so clients receive the new content.

### Can I overwrite a Fastio file via the API?

Publish a new version with POST https://api.fast.io/current/upload/ (multipart fields name, size, chunk, action=create, instance_id, folder_id). Then GET /current/workspace/{workspace_id}/storage/{node_id}/preview/{preview_type}/read/ or GET .../read/. Agents use the MCP upload and storage tools at https://mcp.fast.io/mcp.

### Does rewriting every file in a folder affect performance?

Broad folder work (list every child, then rewrite each file) creates a burst of origin reads. Prefer a single node_id. When you only know a filename, search with name_match=exact or prefix before you write. Use name_match=glob only when you need a pattern.

### How soon can I read the new file after an overwrite?

After a same-name upload returns HTTP 201, the next GET to /read/, /preview/{preview_type}/read/, or /transform/{transform_name}/read/ returns the current file. Multi-file previews such as HLS respond with 307 Temporary Redirect to a sub-file endpoint.

### Can AI agents automate overwrites and preview reads?

Yes. Agents connect to https://mcp.fast.io/mcp and call upload (web-import, stream-upload, create-session, chunk, finalize, batch) then storage (details, version-list, version-restore). Ripley answers questions about the new file through the ai tool with action ask.

## About Fast.io

Fast.io provides shared workspaces where people and AI agents work on the same files, with built-in semantic search and citation-backed chat over what they hold. Agents reach it through a remote MCP server at https://mcp.fast.io/mcp, a REST API at https://api.fast.io/current/, and a command line client published on npm as @vividengine/fastio-cli.