Artifact Workspace

Artifacts-style versioned filesystem workspace. Cloudflare Artifacts bindings are still evolving, so this experiment uses an R2 bucket behind a typed ArtifactStore interface until a stable Artifacts binding is available.

FeaturesCopy Anchor Link

• PUT /files?path= - store text content
• GET /files?path= - read file content
• GET /files/list?prefix= - list paths
• DELETE /files?path= - delete a file

API ReferenceCopy Anchor Link

Path rulesCopy Anchor Link

• Max length 256
• Allowed characters: alphanumeric, /, _, -, .
• No .. segments

PUT /filesCopy Anchor Link

Store text content at a path. Body is raw text.

path string (required)

Example RequestCopy Anchor Link

curl -X PUT "https://your-worker.workers.dev/files?path=notes/hello.txt" \
  -H "Content-Type: text/plain" \
  -d "hello world"

Success ResponseCopy Anchor Link

{
  "path": "notes/hello.txt",
  "stored": true
}

GET /filesCopy Anchor Link

Returns the file body as text/plain, or 404 if missing.

path string (required)

Example RequestCopy Anchor Link

curl "https://your-worker.workers.dev/files?path=notes/hello.txt"

GET /files/listCopy Anchor Link

List stored paths, optionally filtered by prefix.

prefix string (optional)

Example RequestCopy Anchor Link

curl "https://your-worker.workers.dev/files/list?prefix=notes/"

Success ResponseCopy Anchor Link

{
  "files": [{ "path": "notes/hello.txt" }],
  "prefix": "notes/"
}

DELETE /filesCopy Anchor Link

path string (required)

Example RequestCopy Anchor Link

curl -X DELETE "https://your-worker.workers.dev/files?path=notes/hello.txt"

Success ResponseCopy Anchor Link

{
  "path": "notes/hello.txt",
  "deleted": true
}

Error CodesCopy Anchor Link

• 400 - Missing or invalid path/prefix (INVALID_PATH)
• 404 - File does not exist (NOT_FOUND)

Use CasesCopy Anchor Link

• Learn Artifacts-style workspace patterns on Workers
• Store generated code, reports, or build outputs at the edge
• Swap R2 for a future native Artifacts binding via ArtifactStore
• Prototype multi-tenant file APIs with path prefixes

LimitationsCopy Anchor Link

• Uses R2 as a stand-in; not the final Artifacts product API
• Text bodies only in this demo
• Path validation rejects .. and unusual characters
• No authentication or per-user isolation beyond path conventions

DeploymentCopy Anchor Link

curl -X PUT "https://your-worker.workers.dev/files?path=notes/hello.txt" \
  -H "Content-Type: text/plain" \
  -d "hello world"

Local DevelopmentCopy Anchor Link

cd apps/experiments/artifact-workspace
npm install
npm run dev

curl -X PUT "http://localhost:8787/files?path=notes/hello.txt" \
  -H "Content-Type: text/plain" \
  -d "hello world"

ConfigurationCopy Anchor Link

wrangler.json declares:

• R2 bucket ARTIFACTS → artifact-workspace

When a stable Artifacts binding lands, the intended shape is artifacts: [{ binding: "ARTIFACTS", name: "workspace" }]. The ArtifactStore interface isolates route code from the backend.

Cloudflare Features UsedCopy Anchor Link

• Workers - Edge compute runtime
• R2 - Object storage standing in for Artifacts