Downloads API

This is an internal reference for contributors working on the MyClaude codebase. This endpoint is consumed by the web application and CLI — it is not a public developer API.

Product files are never served directly to the browser. Every download goes through a single endpoint that verifies authorization, checks purchase status for paid products, generates a time-limited signed URL, and tracks the download server-side.

Download a product file

Generate a signed URL for downloading a product's file. The URL expires after 5 minutes.

POST /products/download

Auth: Required (Bearer token) Rate limit: 30/min (strict)

Request body

{
  "productId": "abc123"
}

Response

{
  "url": "https://r2-signed-url.example.com/products/my-skill/my-skill.zip?X-Amz-...",
  "fileName": "my-skill.zip"
}

The client should open this URL in a new tab or initiate a download. The URL becomes invalid after expiration or a single use (depending on storage provider configuration).

Access rules

The server applies different authorization rules based on the product's price and the requester's relationship to the product.

Download flow

Client sends POST /products/download
    |
    v
Verify Bearer token (authentication)
    |
    v
Check user is not banned
    |
    v
Fetch product from database
    |
    +-- Not found or unpublished (non-author) --> 404
    |
    v
Is product paid AND requester is not author?
    |
    +-- Yes --> Check orders collection for completed purchase
    |           |
    |           +-- No order found --> 403 "Purchase required"
    |           |
    |           +-- Order exists --> Continue
    |
    +-- No (free or author) --> Continue
    |
    v
Extract storage key from fileUrl
    |
    +-- Path traversal detected --> 400
    |
    v
Generate signed R2 URL (5-min expiry)
    |
    v
Track download (fire-and-forget):
    +-- Write per-user download record (for review eligibility)
    +-- Increment product stats.downloads counter
    |
    v
Return { url, fileName }

Storage architecture

MyClaude uses a hybrid storage model. Product files are stored on Cloudflare R2 (S3-compatible object storage). Presigned URLs are generated server-side using R2 credentials -- the bucket is never directly exposed to clients.

File path format

products/{product-key}/{file-name}.zip

Examples:

products/code-review-skill/code-review-skill.zip
products/my-agent/my-agent-v2.zip

Path security

The server applies strict path validation before generating a signed URL:

If the stored fileUrl is in a legacy format (Firebase Storage download URL or gs:// URI), the server extracts the storage key automatically.

Why signed URLs

Download tracking

Every successful download triggers two asynchronous writes (fire-and-forget, non-blocking):

These writes use merge: true semantics, so repeated downloads by the same user update the timestamp without creating duplicates.

Errors

Example: download via CLI

# Authenticate first
$ myclaude login

# Download a product by slug
$ myclaude install code-review-skill

The CLI resolves the slug to a product ID, calls POST /products/download, and saves the file to the appropriate directory.

Programmatic example

# Get a Firebase ID token (example using firebase-tools)
TOKEN=$(firebase auth:export-token)

# Request a signed download URL
curl -X POST https://myclaude.sh/api/products/download \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"productId": "abc123"}'

# Response:
# { "url": "https://...", "fileName": "my-skill.zip" }

# Download the file
curl -L -o my-skill.zip "SIGNED_URL_FROM_RESPONSE"

Related pages

• API Overview -- Auth model, rate limits, error format
• Payments API -- How purchases are created (prerequisite for paid downloads)
• Products API -- Upload and scan flow (before download is possible)
• Purchasing Guide -- Buyer-facing purchase and download walkthrough
• Security Model -- Signed URL and storage security details