DropWeb API

Quick Start

Create a directory with an index.html, zip it, deploy it:

mkdir mysite && echo "<h1>Hello!</h1>" > mysite/index.html
cd mysite && zip -r ../mysite.zip .
curl -F "site=@../mysite.zip" https://api.dropweb.app/deploy

Response:

{
  "siteId": "gentle-amber-fox",
  "url": "https://gentle-amber-fox.dropweb.app",
  "screenshot": "https://screenshot.dropweb.app/gentle-amber-fox.jpg",
  "expiresAt": "2026-02-19T12:00:00.000Z",
  "files": 1,
  "sizeBytes": 22,
  "key": "sk_a1b2c3d4e5f6...",
  "account": {
    "tier": "anonymous",
    "email": null,
    "sites": 1,
    "sitesLimit": 3,
    "expiryDays": 7
  },
  "hint": "Your site is live at https://gentle-amber-fox.dropweb.app — ..."
}

Deploy a Site

POST /deploy

Upload a ZIP or TAR.GZ archive containing your static site. The archive root must contain an index.html. Only static web files are allowed (HTML, CSS, JS, images, fonts, media).

Request

# Anonymous deploy (returns a new API key)
curl -F "[email protected]" https://api.dropweb.app/deploy

# Authenticated deploy (uses existing account)
curl -F "[email protected]" \
     -H "Authorization: Bearer sk_yourkey" \
     https://api.dropweb.app/deploy

# Key as form field (alternative to header)
curl -F "[email protected]" \
     -F "key=sk_yourkey" \
     https://api.dropweb.app/deploy

# With email — deploys + sends confirmation email
curl -F "[email protected]" \
     -F "[email protected]" \
     https://api.dropweb.app/deploy

Response 201

{
  "siteId": "gentle-amber-fox",
  "url": "https://gentle-amber-fox.dropweb.app",
  "screenshot": "https://screenshot.dropweb.app/gentle-amber-fox.jpg",
  "expiresAt": "2026-02-19T12:00:00.000Z",
  "files": 12,
  "sizeBytes": 48210,
  "key": "sk_...",
  "account": {
    "tier": "anonymous",
    "email": null,
    "sites": 1,
    "sitesLimit": 3,
    "expiryDays": 7
  },
  "hint": "Your site is live at https://gentle-amber-fox.dropweb.app — ..."
}

Redeploy / Update a Site

POST /deploy/:siteId

Replace a site's files with a new archive. Requires authentication. The site ID stays the same, the version increments, and expiry resets.

curl -F "[email protected]" \
     -H "Authorization: Bearer sk_yourkey" \
     https://api.dropweb.app/deploy/gentle-amber-fox

Response 200

{
  "siteId": "gentle-amber-fox",
  "url": "https://gentle-amber-fox.dropweb.app",
  "screenshot": "https://screenshot.dropweb.app/gentle-amber-fox.jpg",
  "version": 2,
  "files": 15,
  "sizeBytes": 61440,
  "account": {
    "tier": "free",
    "email": "[email protected]",
    "sites": 2,
    "sitesLimit": 5,
    "expiryDays": 30
  },
  "hint": "Your site is live at https://gentle-amber-fox.dropweb.app — ..."
}

List Sites

GET /sites

List all sites owned by your account.

curl -H "Authorization: Bearer sk_yourkey" \
     https://api.dropweb.app/sites

Response 200

{
  "sites": [
    {
      "siteId": "gentle-amber-fox",
      "url": "https://gentle-amber-fox.dropweb.app",
      "files": 12,
      "sizeBytes": 48210,
      "version": 1,
      "createdAt": "2026-02-12T12:00:00.000Z",
      "expiresAt": "2026-02-19T12:00:00.000Z"
    }
  ]
}

Get Site Details

GET /sites/:siteId

Get details for a specific site, including its deploy history.

curl -H "Authorization: Bearer sk_yourkey" \
     https://api.dropweb.app/sites/gentle-amber-fox

Response 200

{
  "siteId": "gentle-amber-fox",
  "url": "https://gentle-amber-fox.dropweb.app",
  "files": 15,
  "sizeBytes": 61440,
  "version": 2,
  "createdAt": "2026-02-12T12:00:00.000Z",
  "expiresAt": "2026-02-19T12:00:00.000Z",
  "deploys": [
    { "version": 1, "files": 12, "sizeBytes": 48210, "createdAt": "2026-02-12T12:00:00.000Z" },
    { "version": 2, "files": 15, "sizeBytes": 61440, "createdAt": "2026-02-12T14:30:00.000Z" }
  ]
}

Delete a Site

DELETE /sites/:siteId

Permanently delete a site and all its files.

curl -X DELETE \
     -H "Authorization: Bearer sk_yourkey" \
     https://api.dropweb.app/sites/gentle-amber-fox

Response 200

{
  "message": "Site deleted",
  "siteId": "gentle-amber-fox"
}

Account Status

GET /account

View your current account status, tier, limits, and site count.

curl -H "Authorization: Bearer sk_yourkey" \
     https://api.dropweb.app/account

Response 200

{
  "tier": "anonymous",
  "email": null,
  "sites": 1,
  "sitesLimit": 3,
  "expiryDays": 7,
  "createdAt": "2026-02-12T12:00:00.000Z"
}

Attach Email

POST /account/email

Start the email confirmation process. A confirmation link is sent to the provided email. Once confirmed, your account upgrades to the free tier (more sites, longer expiry, key recovery).

curl -X POST \
     -H "Authorization: Bearer sk_yourkey" \
     -H "Content-Type: application/json" \
     -d '{"email": "[email protected]"}' \
     https://api.dropweb.app/account/email

Response 200

{
  "message": "Confirmation email sent. Check your inbox."
}

Confirm Email

GET /account/confirm?token=...

Called when the user clicks the confirmation link in the email. Validates the token, upgrades the account to the free tier, extends all site expiry dates, and redirects.

Response 302

Redirects to the configured landing page. On invalid or expired tokens, returns a 400 error.

Recover Account

POST /account/recover

Lost your API key? If you confirmed an email, request a new key. A recovery email is sent with a fresh key. The old key is invalidated immediately.

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{"email": "[email protected]"}' \
     https://api.dropweb.app/account/recover

Response 200

{
  "message": "If this email exists, a new key has been sent."
}

Authentication

Most endpoints require an API key. Pass it in one of two ways:

Authorization Header (recommended)

curl -H "Authorization: Bearer sk_yourkey" https://api.dropweb.app/sites

Form Field

curl -F "[email protected]" -F "key=sk_yourkey" https://api.dropweb.app/deploy

How Keys Work

When you deploy anonymously, the response includes a key field starting with sk_. It is shown only once and cannot be recovered without a confirmed email on file.

Keys are hashed server-side. We never store your plaintext key.

Public Endpoints (no key required)

Authenticated Endpoints

Tiers

Accounts start as anonymous and upgrade to free after confirming an email.

Upgrading extends all existing site expiry dates to 30 days.

Rate Limits & Quotas

Rate-limited requests return 429 with a Retry-After header indicating seconds until the next allowed request. The response body also includes a retryAfter field:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Wait a moment and try again.",
    "retryAfter": 120
  }
}

Error Codes

All errors follow this structure:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Description with next steps"
  }
}