API Docs

Reference for upload, update, delete, request fields, limits, expiry behavior, and common error responses.

Base URL

https://api.htmlbucket.com

Authentication

Supported headers

API key headers are optional for POST /v1/upload and required for PUT/DELETE:

  • X-API-Key: YOUR_KEY
  • Authorization: Bearer YOUR_KEY
  • Authorization: Basic <base64(api:YOUR_KEY)>
For Basic auth, username must be api. Anonymous POST is limited to the none plan with 1/minute IP rate limiting.

Public fetch

  • GET https://<id>.htmlbucket.com
  • GET https://<id>.htmlbucket.com/<asset-path>
Public fetch is unrestricted until upload expiry. Root serves index.html; subpaths serve additional files in the upload folder.

Endpoints

Method Path Description
POST /v1/upload Create a new upload. Counts as 1 daily write when successful.
PUT /v1/upload/{id} Update an upload you own. Counts as 1 daily write when successful.
DELETE /v1/upload/{id} Delete an upload you own. Does not count toward daily writes.
GET https://{id}.htmlbucket.com Fetch index.html for a non-expired upload.
GET https://{id}.htmlbucket.com/{path} Fetch an additional file from a non-expired upload folder.
PROPFIND, GET, PUT, MKCOL, DELETE, OPTIONS /v1/dav/... Authenticated WebDAV operations for per-user folder/file management.

WebDAV Notes

  • WebDAV root is /v1/dav/.
  • Auth uses the same API key headers as upload endpoints.
  • PROPFIND /v1/dav/ lists active upload folders owned by the authenticated user.
  • New upload IDs still come from POST /v1/upload; each new upload starts with index.html.

Request Fields (JSON)

Field Type Required Notes
content string Yes HTML body to store. Empty string is rejected.
expiry integer (unix seconds) No Must be in the future and within your plan max window. If omitted on create, defaults to the plan max window from now.
title string No Optional upload title. Trimmed; max 120 chars. On PUT, omitted title preserves existing title.

JSON Examples

Create

curl -sS -X POST https://api.htmlbucket.com/v1/upload \ -H 'Content-Type: application/json' \ -H 'X-API-Key: YOUR_KEY' \ -d '{ "content": "<h1>Hello bucket</h1>", "title": "Landing page preview", "expiry": 1767225600 }' # 200 response {"url":"https://abc123.htmlbucket.com"}

Update

curl -sS -X PUT https://api.htmlbucket.com/v1/upload/ENTRY_ID \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_KEY' \ -d '{ "content": "<h1>Updated content</h1>", "title": "Updated title", "expiry": 1767229200 }' # 200 response {"url":"https://ENTRY_ID.htmlbucket.com"}

Delete

curl -sS -X DELETE https://api.htmlbucket.com/v1/upload/ENTRY_ID \ -H 'X-API-Key: YOUR_KEY' # 204 No Content

Multipart Form Uploads

For browser extensions and form integrations, POST /v1/upload also accepts multipart/form-data.

curl -sS -X POST https://api.htmlbucket.com/v1/upload \ -H 'Authorization: Bearer YOUR_KEY' \ -F '[email protected];type=text/html' \ -F 'title=Example page' \ -F 'expiry=1767225600'
  • The first file part (any field name) is used as upload content.
  • If no file part is present, content form field is used instead.
  • Optional form fields: title, expiry.
  • Unknown extra form fields are ignored.

Multipart Site Uploads

To create a full site in one request, send upload_kind=site and put each file's relative site path in the multipart field name using the file:<relative-path> pattern.

curl -sS -X POST https://api.htmlbucket.com/v1/upload \ -H 'Authorization: Bearer YOUR_KEY' \ -F 'upload_kind=site' \ -F 'title=dist build' \ -F 'file:index.html=@dist/index.html;type=text/html' \ -F 'file:assets/app.js=@dist/assets/app.js;type=application/javascript' \ -F 'file:assets/app.css=@dist/assets/app.css;type=text/css'
  • Root index.html is required.
  • Anonymous site uploads are limited to 10 MiB total across all files.
  • API-key site uploads are limited to 50 MiB total across all files.
  • Single-file JSON uploads and PUT /v1/upload/{id} still use the per-plan single-file size limits below.

Plan Limits

Plan Writes / day Max single-file size Max expiry window Storage cap (active)
None (anonymous) 20 1 MiB 3 hours 5 GiB shared across all anonymous uploads
Free 50 10 MiB 7 days 500 MiB
Pro 200 10 MiB 30 days 5 GiB
Team 5000 25 MiB 90 days 100 GiB
Multipart site creates use total upload-size limits of 10 MiB anonymous and 50 MiB with an API key.
Unknown API-key plan names are treated as free. Legacy hobby values resolve to free.

Status Codes

  • 200 OK create/update success, returns {"url":"..."}
  • 204 No Content delete success
  • 400 Bad Request invalid JSON/form, empty content, invalid title, invalid expiry
  • 401 Unauthorized missing/invalid API key on authenticated endpoints
  • 403 Forbidden API key disabled/forbidden
  • 404 Not Found missing upload, expired upload, or upload not owned by caller
  • 405 Method Not Allowed wrong HTTP method
  • 413 Payload Too Large body exceeds request size cap or plan size cap
  • 429 Too Many Requests daily write limit or active storage cap exceeded
© htmlbucket docs