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

One of these headers is required for write endpoints:

  • X-API-Key: YOUR_KEY
  • Authorization: Bearer YOUR_KEY
All write endpoints require an API key.

Public fetch

  • GET https://<id>.htmlbucket.com
Public fetch is unrestricted until upload expiry.

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 rendered HTML for a non-expired upload.

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.

Plan Limits

Plan Writes / day Max upload size Max expiry window Storage cap (active)
Free 20 1 MiB 3 hours 20 MiB
Hobby 50 10 MiB 3 days 500 MiB
Pro 200 10 MiB 30 days 5 GiB
Team 5000 25 MiB 90 days 100 GiB
Unknown plan names are treated as 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
  • 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