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, and common image formats (jpg, png, gif, webp, svg). 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.
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.