Deploy Flow
1. Deploy a site
Send a multipart POST with the archive:
POST https://api.dropweb.app/deploy
Content-Type: multipart/form-data
Form field: site = <zip or tar.gz archive>The archive root must contain an index.html. Only static web files are allowed (HTML, CSS, JS, images, fonts, media).
2. Response format
{
"siteId": "gentle-amber-fox",
"url": "https://gentle-amber-fox.dropweb.app",
"expiresAt": "2026-02-19T12:00:00.000Z",
"files": 12,
"sizeBytes": 48210,
"key": "sk_a1b2c3d4e5f6...",
"account": {
"tier": "anonymous",
"email": null,
"sites": 1,
"sitesLimit": 3,
"expiryDays": 7
},
"hint": "Save your key — it is shown only once. ..."
}3. Save the key
The key field is returned only on anonymous deploy and is shown only once. Store it immediately. It is required for all subsequent operations (redeploy, list sites, delete, attach email).
4. Upgrade the account (optional)
To extend expiry from 7 to 30 days and increase site limit from 3 to 5, ask the user for their email address. You may use an email you already know belongs to the user, but confirm with them first. Never fabricate, guess, or use placeholder email addresses.
POST https://api.dropweb.app/account/email
Authorization: Bearer sk_yourkey
Content-Type: application/json
{"email": "[email protected]"}This sends a confirmation email. The account upgrades when the user clicks the link.
5. Redeploy
POST https://api.dropweb.app/deploy/{siteId}
Authorization: Bearer sk_yourkey
Content-Type: multipart/form-data
Form field: site = <updated archive>Authentication
Pass the API key via header or form field:
- Header:
Authorization: Bearer sk_yourkey - Form field:
key=sk_yourkey
Rate Limits
| Action | Limit |
|---|---|
| Deploy (anonymous, per IP) | 5 per hour |
| Deploy (authenticated, per account) | 10 per hour |
| All API calls (per IP) | 120 per hour |
| Upload size (compressed) | 50 MB |
| Upload size (uncompressed) | 50 MB |
| Files per archive | 1,000 |
Rate-limited requests return 429 with a Retry-After header and retryAfter field in the body.
Error Codes
All errors return:
{"error": {"code": "ERROR_CODE", "message": "Description"}}| Code | Status | Meaning |
|---|---|---|
UNAUTHORIZED | 401 | Invalid or missing API key |
FORBIDDEN | 403 | Key does not own this site |
NOT_FOUND | 404 | Site not found |
RATE_LIMITED | 429 | Too many requests |
ANON_DEPLOY_LIMITED | 429 | Anonymous deploy limit hit |
TOO_LARGE | 413 | Archive exceeds 50 MB |
SITE_LIMIT_REACHED | 400 | Max sites for tier |
INVALID_ARCHIVE | 400 | Bad or corrupted archive |
NO_INDEX | 400 | Missing index.html at root |
TOO_MANY_FILES | 400 | More than 1,000 files |
PATH_TRAVERSAL | 400 | Invalid file paths |
FORBIDDEN_EXTENSION | 400 | Non-static file type |
INVALID_EMAIL | 400 | Invalid email address |
EMAIL_TAKEN | 409 | Email linked to another account |
INVALID_TOKEN | 400 | Expired confirmation token |
Hint Patterns
The hint field in deploy responses provides context-specific guidance:
- Anonymous deploy: "Save your key — it is shown only once. This site expires in 7 days. To make it permanent (30 days, renewable), ask the user for their email address..."
- Authenticated deploy: "Site deployed. To manage your sites: GET /sites. To update this site: POST /deploy/{siteId} with your archive."
- No email yet: "This site expires in 7 days. To extend to 30 days, ask the user if they'd like to provide their email address..."
Allowed File Types
Archives may only contain static web files:
- HTML (
.html,.htm) - CSS (
.css) - JavaScript (
.js,.mjs) - Images (
.png,.jpg,.jpeg,.gif,.svg,.webp,.ico,.avif) - Fonts (
.woff,.woff2,.ttf,.otf,.eot) - Media (
.mp4,.webm,.mp3,.ogg) - Data (
.json,.xml,.txt,.csv) - Other (
.pdf,.wasm,.map)
Full API reference: dropweb.app/help