Comfy-Org · huntcsg · Dec 31, 2025
diff --git a/cloud/sdk/authentication.mdx b/cloud/sdk/authentication.mdx
@@ -0,0 +1,135 @@
+---
+title: "Authentication"
+description: "Authenticate with the ComfyUI Cloud Developer API"
+---
+
+## API Keys
+
+All Developer API requests require authentication via API key. These are the same API keys used for [Partner Nodes](/tutorials/partner-nodes/overview) and other Comfy platform features.
+
+### Getting Your API Key
+
+API keys are managed at [platform.comfy.org](https://platform.comfy.org/login):
+
+<Steps>
+  <Step title="Visit platform.comfy.org and Log In">
+    Go to [platform.comfy.org/login](https://platform.comfy.org/login) and sign in with your Comfy account (Email, Google, or GitHub).
+    ![Visit Platform Login Page](/images/interface/setting/user/user-login-api-key-1.jpg)
+  </Step>
+  <Step title="Create an API Key">
+    Click **+ New** in the API Keys section.
+    ![Create API Key](/images/interface/setting/user/user-login-api-key-2.jpg)
+  </Step>
+  <Step title="Name Your Key">
+    Enter a descriptive name (e.g., "Production Backend", "Local Dev") and click **Generate**.
+    ![Enter API Key Name](/images/interface/setting/user/user-login-api-key-3.jpg)
+  </Step>
+  <Step title="Save Your Key">
+    Copy and save your API key immediately.
+    ![Obtain API Key](/images/interface/setting/user/user-login-api-key-4.jpg)
+    <Warning>
+      The API key is only shown once at creation. Store it securely - you cannot view it again later.
+    </Warning>
+  </Step>
+</Steps>
+
+### Managing API Keys
+
+You can view and delete your API keys at [platform.comfy.org](https://platform.comfy.org/login):
+
+![API Key Management](/images/interface/setting/user/user-login-api-key-5.jpg)
+
+Delete any unused keys or keys that may have been compromised.
+
+## Using Your API Key
+
+Include the API key in the `Authorization` header:
+
+```bash
+curl https://cloud.comfy.org/developer/api/v1/account \
+  -H "Authorization: Bearer comfyui-abc123..."
+```
+
+With the Python SDK:
+
+```python
+from comfy_cloud import ComfyCloudClient
+
+client = ComfyCloudClient(api_key="comfyui-abc123...")
+```
+
+### Environment Variables
+
+We recommend storing your API key in environment variables:
+
+```bash
+export COMFY_API_KEY="comfyui-abc123..."
+```
+
+```python
+import os
+from comfy_cloud import ComfyCloudClient
+
+client = ComfyCloudClient(api_key=os.environ["COMFY_API_KEY"])
+```
+
+<Warning>
+Never commit API keys to version control. Use environment variables or a secrets manager.
+</Warning>
+
+## Environments
+
+| Environment | Base URL |
+|-------------|----------|
+| Production | `https://cloud.comfy.org/developer/api/v1` |
+| Staging | `https://stagingcloud.comfy.org/developer/api/v1` |
+
+```python
+# Using staging
+client = ComfyCloudClient(
+    api_key="comfyui-...",
+    base_url="https://stagingcloud.comfy.org/developer/api/v1",
+)
+```
+
+## Rate Limits
+
+The API has rate limits to ensure fair usage:
+
+| Limit | Value |
+|-------|-------|
+| Requests per minute | 600 |
+| Concurrent jobs | Based on plan |
+| Max upload size | 100 MB |
+
+When rate limited, you'll receive a `429 Too Many Requests` response. Implement exponential backoff in your retry logic.
+
+## Error Responses
+
+Authentication errors return `401 Unauthorized`:
+
+```json
+{
+  "error": {
+    "type": "unauthorized",
+    "message": "Invalid or expired API key"
+  }
+}
+```
+
+Common causes:
+- Missing `Authorization` header
+- Malformed header (should be `Bearer <key>`)
+- Revoked or deleted API key
+- Using wrong environment's key
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Account Login" icon="user" href="/account/login">
+    Full account management and login options
+  </Card>
+  <Card title="Partner Nodes" icon="plug" href="/tutorials/partner-nodes/overview">
+    Using API keys with Partner Nodes
+  </Card>
+</CardGroup>
diff --git a/cloud/sdk/overview.mdx b/cloud/sdk/overview.mdx
@@ -0,0 +1,107 @@
+---
+title: "Developer API Overview"
+description: "Programmatic access to ComfyUI Cloud for building applications and automations"
+---
+
+The ComfyUI Cloud Developer API provides a clean, SDK-friendly interface for running ComfyUI workflows programmatically. Use it to build applications, batch processing pipelines, or integrate AI image generation into your products.
+
+## Why Use the Developer API?
+
+<CardGroup cols={2}>
+  <Card title="Clean REST Semantics" icon="code">
+    Designed for developers, not constrained by ComfyUI frontend compatibility
+  </Card>
+  <Card title="Official SDKs" icon="box">
+    Type-safe clients for Python, JavaScript, and Go
+  </Card>
+  <Card title="Real-time Events" icon="bolt">
+    WebSocket streaming for live progress updates
+  </Card>
+  <Card title="Webhooks" icon="webhook">
+    Push notifications when jobs complete
+  </Card>
+</CardGroup>
+
+## Core Concepts
+
+### Resources
+
+| Resource | Description |
+|----------|-------------|
+| **Inputs** | Files you upload for use in workflows (images, masks, etc.) |
+| **Models** | Custom models you bring (BYOM - Bring Your Own Model) |
+| **Jobs** | Workflow executions |
+| **Outputs** | Generated files from completed jobs |
+| **Archives** | Bulk ZIP downloads of multiple job outputs |
+| **Webhooks** | Event notifications to your server |
+
+### Async Patterns
+
+Many operations are asynchronous:
+
+1. **Create** - Returns `202 Accepted` with resource in pending state
+2. **Poll** - Check status until `ready` or `failed`
+3. **Use** - Access the resource once ready
+
+```python
+# Example: Upload from URL (async operation)
+input = client.inputs.from_url("https://example.com/image.png")
+# Status is "downloading"
+
+# Poll for completion
+while input.status == "downloading":
+    time.sleep(1)
+    input = client.inputs.get(input.id)
+
+# Now ready to use
+print(input.name)  # Use this in your workflow
+```
+
+Or use WebSockets for real-time updates without polling.
+
+## Quick Example
+
+```python
+from comfy_cloud import ComfyCloudClient
+
+client = ComfyCloudClient(api_key="comfyui-...")
+
+with client:
+    # Run a workflow
+    job = client.jobs.create(
+        workflow={
+            "3": {
+                "class_type": "KSampler",
+                "inputs": {"seed": 42, "steps": 20, ...}
+            },
+            # ... rest of workflow
+        },
+        tags=["my-app", "batch-1"],
+    )
+
+    # Wait for completion
+    while job.status == "pending":
+        job = client.jobs.get(job.id)
+
+    # Get outputs
+    outputs = client.outputs.list(job_id=job.id)
+    for output in outputs.outputs:
+        print(f"Download: {output.download_url}")
+```
+
+## Next Steps
+
+<CardGroup cols={2}>
+  <Card title="Authentication" icon="key" href="/cloud/sdk/authentication">
+    Get your API key and authenticate requests
+  </Card>
+  <Card title="Python SDK" icon="python" href="/cloud/sdk/python">
+    Full Python SDK reference and examples
+  </Card>
+  <Card title="WebSockets" icon="plug" href="/cloud/sdk/websockets">
+    Real-time event streaming
+  </Card>
+  <Card title="Webhooks" icon="bell" href="/cloud/sdk/webhooks">
+    Push notifications for job events
+  </Card>
+</CardGroup>