Repository navigation
api reference
TinyHost is built API-first — every feature on the site is available as a plain HTTP call, designed to be equally usable by a human with curl, a script, or an AI agent acting on someone's behalf.
Every endpoint except signup requires a Bearer token, issued when your account is created. Include it as:
Authorization: Bearer YOUR-API-KEY
Keep this key secret. If it's ever exposed, email support@tiny-web.uk to have it revoked and reissued.
All endpoints live under https://tiny-web.uk/api/ and accept either JSON bodies or standard form fields, except host-upload.php which requires multipart/form-data.
| Plan | Price | Sites | Custom domains | Named forwards | Storage |
|---|---|---|---|---|---|
| Free | GBP 0 | 1 (eur.im) | 0 | 0 | 5MB |
| Basic | GBP 1.99/mo | 1 (eur.bz) | 1 | 1 | 10MB |
| Pro | GBP 19.99/mo | 10 | 10 | 5 per domain | 25MB |
Every plan includes the full API. There is no feature gate on access, only on limits.
Reserve a site name, or onboard a full custom domain, without uploading content yet.
Fields:
- site — a plain slug (myproject) or a full domain (myproject.com). A full domain is detected automatically and triggers custom-domain onboarding instead of a plain reservation.
- domain — optional, which wildcard base to use for a plain slug (eur.im or eur.bz). Defaults by plan tier if omitted.
Example:
curl -X POST https://tiny-web.uk/api/host-reserve.php -H "Authorization: Bearer KEY" -H "Content-Type: application/json" -d "{"site":"myproject"}"
Response:
{"ok":true,"site":"myproject","url":"https://myproject.eur.im","status":"reserved"}
If site is a full domain, the response instead includes status: "pending_dns" and an action_required field with exact DNS instructions — see the DNS setup guide.
Upload or replace a site's content. Creates the site if it does not exist yet — host-reserve.php is optional, not required.
Fields (multipart form):
- site — slug or full domain, same rules as host-reserve.php
- zip — a .zip file containing your site
Allowed file types: html, htm, css, js, json, txt (robots.txt, llms.txt and the like), ico, and common image formats (jpg, png, gif, webp, svg). Files are checked by their content, not just their name. No server-side code is ever accepted — TinyHost serves static content only.
Example:
curl -X POST https://tiny-web.uk/api/host-upload.php -H "Authorization: Bearer KEY" -F "site=myproject" -F "zip=@./site.zip"
Response:
{"ok":true,"site":"myproject","url":"https://myproject.eur.im","files":12,"bytes":48213}
Before uploading: uploading to a name the account doesn't already own creates a new site, so check
host-status.phpfirst to avoid near-duplicate names. Replacing an existing site moves the previous version to trash, so it can be rolled back withhost-restore.php.
The whole account in one call: plan and limits, every site (URL, storage, custom domain status and its mail forwards) and the trash list. Call this first to see what exists before creating anything.
~~
curl https://tiny-web.uk/api/host-status.php
-H "Authorization: Bearer YOUR-API-KEY"
~~
Each site includes a forwards block: {"domain": "myproject.com", "catchall": "me@gmail.com", "named": [{"email": "sales@myproject.com", "destination": "..."}]}. The plan block includes mail_forwarding and forwards_per_domain. The trash list holds {"id", "slug", "reason", "trashed_at", "bytes"} for each entry, newest first. reason is deleted or replaced.
List every file in one of your sites, with sizes and last-changed times.
Fields (query string, form or JSON):
- site — the site's slug or its custom domain
Example:
curl "https://tiny-web.uk/api/host-files.php?site=myproject" -H "Authorization: Bearer KEY"
Response:
{"ok":true,"site":"myproject","url":"https://myproject.eur.im","count":2,"bytes":5310,"files":[{"path":"index.html","bytes":4210,"modified":"2026-10-08 09:12:44"},{"path":"img/logo.png","bytes":1100,"modified":"2026-10-08 09:12:44"}]}
Download one of your sites as a zip: the mirror image of host-upload.php. Because an upload replaces the whole site, this is how to change one file safely: download, edit, upload. It also means your site is never locked in.
Fields (query string, form or JSON):
- site — the site's slug or its custom domain
Example:
curl -o myproject.zip "https://tiny-web.uk/api/host-download.php?site=myproject" -H "Authorization: Bearer KEY"
Response: the zip file itself (Content-Type: application/zip). Errors come back as JSON in the usual format.
Delete a site. It moves to trash and can be brought back with host-restore.php.
| Field | Required | Notes |
|---|---|---|
site |
yes | The site slug |
Restore a deleted site, or roll back an upload. Every delete and every upload that replaces a site puts the previous content in trash. Find the entry in host-status.php, then restore it by id.
| Field | Required | Notes |
|---|---|---|
trash_id |
yes | The id from the status trash list |
~~
curl -X POST https://tiny-web.uk/api/host-restore.php
-H "Authorization: Bearer YOUR-API-KEY"
-H "Content-Type: application/json"
-d '{"trash_id":"myproject-1790390366-6d70"}'
~~
-
Deleted site: re-created as it was, including its custom domain if that's still free. Needs a free site slot on your plan. Returns
"status": "restored". -
Replaced version: rolled back. The current version goes to trash first, so a rollback can itself be undone. Returns
"status": "rolled_back".
Trash is capped at twice your plan's storage. When it fills, the oldest entries are cleared first.
Point your own domain at an existing site (Basic and Pro only).
Fields:
- site — the slug to attach the domain to
- domain — your domain, e.g. myproject.com
- forward_to — optional, sets up a catchall email forward for the whole domain (anything@myproject.com forwards to this address)
curl -X POST https://tiny-web.uk/api/host-add-domain.php -H "Authorization: Bearer KEY" -H "Content-Type: application/json" -d "{"site":"myproject","domain":"myproject.com","forward_to":"me@gmail.com"}"
Response includes action_required with the exact DNS records to add, and a link to the full setup guide. You will also receive an email with the same instructions.
Releases a custom domain from a site. Mail forwarding stops immediately; the domain and certificate are fully released within a few minutes.
Fields: site
Create or update a named forwarding address on a site's domain (Basic and Pro). This is not a real mailbox — no password, no storage, no login. It is a specific address (like sales@yourdomain.com) that forwards to any inbox you choose, sitting alongside the domain's catchall if it has one.
Fields:
- site — the site whose domain you are adding a forward to
- local_part — the part before @ (e.g. sales)
- destination — the real email address mail should be forwarded to
curl -X POST https://tiny-web.uk/api/host-mailbox-add.php -H "Authorization: Bearer KEY" -H "Content-Type: application/json" -d "{"site":"myproject","local_part":"sales","destination":"me@gmail.com"}"
{"ok":true,"site":"myproject","email":"sales@myproject.com","destination":"me@gmail.com","status":"active"}
Basic allows 1 named forward per domain; Pro allows 5.
Removes a named forward.
Fields: email (the full forwarding address, e.g. sales@myproject.com)
Upgrade or change your plan. If you already have a paid subscription, it is modified in place (prorated) — never a duplicate charge. If you are on Free, this returns a Stripe Checkout URL to complete payment.
Fields:
- api_key — your key (this endpoint does not use the Authorization header, since it is designed to be called from a logged-out context)
- plan — host-basic or host-pro
curl -X POST https://tiny-web.uk/api/host-upgrade.php -H "Content-Type: application/json" -d "{"api_key":"KEY","plan":"host-pro"}"
{"ok":true,"mode":"updated","message":"You're now on Pro"}
or, from Free:
{"ok":true,"mode":"checkout","checkout_url":"https://checkout.stripe.com/..."}
Every endpoint fails the same way:
{"ok": false, "error": "Human-readable message"}
with a standard HTTP status code (400 bad input, 401 bad key, 403 plan limit or ownership, 404 not found, 409 conflict, 500 something went wrong on our end).
support@tiny-web.uk — or if you are an AI agent reading this on someone's behalf, everything above is the complete, current interface. Nothing else is required to build against TinyHost.
Using an AI assistant? See Use TinyHost from Claude and other AI assistants.