Sites - htmldrop

Base URL is https://htmldrop.app/api/v1. Every endpoint here needs an API token.

Most authenticated endpoints require a verified email and return 403 {"error":"email_not_verified"} otherwise. The exceptions — so a new account can get one site live before confirming — are POST /sites, GET /sites, GET /sites/{id}, DELETE /sites/{id}, POST /sites/{id}/upload and POST /sites/{id}/upload-bundle. In practice this only affects dashboard sessions: API tokens can only be created by an already-verified account.

Create a site

POST /sites

Both fields are optional — omit slug for a random one, omit name to leave it blank.

curl -X POST https://htmldrop.app/api/v1/sites \
  -H "Authorization: Bearer $HTMLDROP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"slug": "my-project", "name": "My Project"}'

Returns 201:

{
  "id": "st_...",
  "slug": "my-project",
  "name": "My Project",
  "access_mode": "public",
  "has_password": false,
  "branding_enabled": true
}

Creating a site only reserves the slug — it has no content until you upload.

Upload a single file

POST /sites/{id}/upload

Multipart with one file field: .html/.htm is served as-is, .md is rendered to HTML. Every upload creates a version and promotes it live.

curl -X POST https://htmldrop.app/api/v1/sites/st_.../upload \
  -H "Authorization: Bearer $HTMLDROP_API_TOKEN" \
  -F "file=@./index.html"

Returns 201:

{ "version_id": "v_...", "version_number": 2, "byte_size": 4213, "file_count": 1 }

Upload a folder or .zip

POST /sites/{id}/upload-bundle

Two accepted shapes:

Files and paths
A single .zip

Repeated files fields with a parallel paths field giving each file’s relative path. This is what the dashboard’s folder picker sends, and what multipart clients that can’t preserve directory structure should use.

curl -X POST https://htmldrop.app/api/v1/sites/st_.../upload-bundle \
  -H "Authorization: Bearer $HTMLDROP_API_TOKEN" \
  -F "files=@./dist/index.html"       -F "paths=index.html" \
  -F "files=@./dist/assets/app.css"   -F "paths=assets/app.css" \
  -F "files=@./dist/assets/app.js"    -F "paths=assets/app.js"

One file field whose filename ends in .zip. htmldrop extracts it server-side and deploys the contents.

curl -X POST https://htmldrop.app/api/v1/sites/st_.../upload-bundle \
  -H "Authorization: Bearer $HTMLDROP_API_TOKEN" \
  -F "file=@./site.zip"

Either way index.html must exist at the root of the bundle. The response has the same shape as a single-file upload.

List and read

curl https://htmldrop.app/api/v1/sites \
  -H "Authorization: Bearer $HTMLDROP_API_TOKEN"

curl https://htmldrop.app/api/v1/sites/st_... \
  -H "Authorization: Bearer $HTMLDROP_API_TOKEN"

GET /sites returns an array; GET /sites/{id} returns one site in the same shape POST /sites returns.

Update settings

PATCH /sites/{id} changes a site’s configuration — name, slug, password, analytics, and spa_fallback:

curl -X PATCH https://htmldrop.app/api/v1/sites/{id} \
  -H "Authorization: Bearer $HTMLDROP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"spa_fallback": true}'

Delete

curl -X DELETE https://htmldrop.app/api/v1/sites/st_... \
  -H "Authorization: Bearer $HTMLDROP_API_TOKEN"

Returns 204. Deletion is immediate and permanent.

The authenticated account

curl https://htmldrop.app/api/v1/me \
  -H "Authorization: Bearer $HTMLDROP_API_TOKEN"

Returns the signed-in user and tenant: email, verification status, plan, role, and the organisations available to switch between.

Usage and export

curl https://htmldrop.app/api/v1/usage  -H "Authorization: Bearer $HTMLDROP_API_TOKEN"
curl https://htmldrop.app/api/v1/sites/export -H "Authorization: Bearer $HTMLDROP_API_TOKEN" -o export.zip

usage reports consumption against your plan’s caps. export returns every drop as a .zip — there is no lock-in and no export fee.

​Create a site

​Upload a single file

​Upload a folder or .zip

​List and read

​Update settings

​Delete

​The authenticated account

​Usage and export

Create a site

Upload a single file

Upload a folder or .zip

List and read

Update settings

Delete

The authenticated account

Usage and export