diff --git a/development/cloud/assets-vs-files.mdx b/development/cloud/assets-vs-files.mdx
new file mode 100644
index 000000000..7de441674
--- /dev/null
+++ b/development/cloud/assets-vs-files.mdx
@@ -0,0 +1,114 @@
+---
+title: "Assets vs Files: Uploading Inputs to Comfy Cloud"
+description: "Understand the differences between the Assets API and File API for uploading inputs to Comfy Cloud"
+---
+
+<Warning>
+**Experimental API:** This API is experimental and subject to change. Endpoints, request/response formats, and behavior may be modified without notice.
+</Warning>
+
+## Overview
+
+Comfy Cloud provides two separate systems for uploading files: the **Assets API** and the **File API**. These serve different purposes and behave differently from local ComfyUI. This guide explains the distinction and helps you choose the right approach.
+
+## Assets vs Files: What's the Difference?
+
+| | Assets API (`/api/assets`) | File API (`/api/upload/image`) |
+|---|---|---|
+| **Purpose** | Persistent, reusable storage | Workflow input for a specific job |
+| **Storage** | Content-addressed (hash-based) | Tag-based organization |
+| **Deduplication** | Yes: same content returns existing asset | No |
+| **Use as workflow input** | Yes (under confirmation, see below) | Yes |
+| **Recommended for** | Models, reusable images, large files | One-off job inputs |
+| **Legacy compatibility** | New API | Drop-in compatible with local ComfyUI |
+
+<Note>
+**Recommendation:** For new integrations, use the Assets API. The File API exists primarily for compatibility with existing ComfyUI clients.
+</Note>
+
+## Uploading Assets
+
+The Assets API supports two upload methods.
+
+### Method 1: Direct File Upload (Recommended)
+
+Use `multipart/form-data` to upload a file directly from your local machine or application.
+
+```bash
+curl -X POST https://cloud.comfy.org/api/assets \
+  -H "X-API-Key: ***" \
+  -F "file=@/path/to/your/image.png" \
+  -F "tags=input" \
+  -F "name=my-image.png"
+```
+
+This method works reliably for all supported file types including images, audio, and video.
+
+### Method 2: URL-Based Upload
+
+Use `application/json` to upload an asset from a remote URL.
+
+```bash
+curl -X POST https://cloud.comfy.org/api/assets \
+  -H "X-API-Key: ***" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "url": "https://example.com/image.png",
+    "name": "image.png",
+    "tags": ["input"]
+  }'
+```
+
+<Warning>
+**URL-based uploads have specific source requirements.** See the Supported Sources section below before using this method.
+</Warning>
+
+## Supported Sources for URL-Based Uploads
+
+The URL must be reachable by Comfy Cloud servers. The exact set of supported sources and validation rules may expand over time. Refer to the actual error response for guidance if a URL upload is rejected. Common errors include:
+
+| HTTP Status | Meaning |
+|---|---|
+| `403` | Source URL requires authentication or access denied |
+| `404` | Source URL not found |
+| `415` | Unsupported media type |
+| `422` | Download failed due to network error or timeout |
+
+If you encounter repeated failures with public URLs, switch to **direct file upload (Method 1)** as the most reliable alternative.
+
+<Info>
+After uploading, the behaviour of referencing an asset in a workflow JSON via `POST /api/prompt` is under confirmation. See [issue #754](https://github.com/Comfy-Org/docs/issues/754) for tracking.
+</Info>
+
+## Deduplication Behavior
+
+The Assets API uses **content-addressed storage** based on a Blake3 hash of the file contents. If you upload the same file twice, the API returns the existing asset rather than creating a duplicate. The response will include `"created_new": false`.
+
+This means:
+
+- `200` = asset already existed, existing asset returned
+- `201` = new asset created successfully
+
+## Quick Reference: Which Method Should I Use?
+
+Need to upload a file for a workflow?
+
+```text
+│
+├── Is it a file you'll reuse across multiple jobs?
+│   └── YES → Use Assets API (POST /api/assets, multipart/form-data)
+│
+├── Is it a one-time input for a single job?
+│   └── YES → File API (POST /api/upload/image) works fine
+│
+└── Are you migrating from local ComfyUI?
+    └── YES → File API is drop-in compatible, no changes needed
+```
+
+## Related Endpoints
+
+- `POST /api/assets` - Upload a new asset
+- `GET /api/assets` - List your uploaded assets
+- `GET /api/assets/{id}` - Get asset details
+- `POST /api/upload/image` - Legacy file upload (workflow input)
+- `GET /api/view` - View/download a file
diff --git a/docs.json b/docs.json
index 3457c18be..54cc12bcb 100644
--- a/docs.json
+++ b/docs.json
@@ -2597,7 +2597,8 @@
                     "pages": [
                       "development/cloud/overview",
                       "development/cloud/api-reference",
-                      "development/cloud/openapi"
+                      "development/cloud/openapi",
+                      "development/cloud/assets-vs-files"
                     ]
                   },
                   {