| name | yourwebs |
| description | Use when the user wants to publish, host, or share a self-contained HTML page or artifact on yourweb (yourwebs.cc) — getting a public URL — or to list, fetch, update, or delete their hosted pages via the yourweb REST API. |
Publish HTML to yourweb
Host a single self-contained HTML file on yourweb and get a
public, full-screen URL. The REST API lets an agent publish a page, then list,
fetch, update, and delete the pages it owns.
Two domains, by design:
yourwebs.cc — the dashboard and the REST API (https://yourwebs.cc/api/v1).yourwebs.app — where published pages are served. A page with subdomain
my-page is served at https://my-page.yourwebs.app.
Authentication
Every call except anonymous publish needs a bearer token (ywb_...), generated by
the user in the yourweb dashboard.
Read the token from the YOURWEBS_API_TOKEN environment variable. Never hardcode
it, never write it into a file, never echo it back.
If YOURWEBS_API_TOKEN is unset, stop and ask the user to set it:
export YOURWEBS_API_TOKEN="ywb_..."
Only if the user explicitly prefers to paste the token inline, use it for this
session — and warn them it will appear in the chat transcript, so the env var is
preferred. If a project keeps it in a .env file, make sure .env is gitignored.
Publish a page (the main task)
- Write a single, self-contained HTML file (inline CSS/JS, no external build).
It must be UTF-8, contain
<!doctype html> or <html>, and be ≤ 1 MB.
- Wrap it in a JSON body and POST it. Use
jq to build the JSON so the HTML is
escaped correctly — never hand-concatenate HTML into a JSON string.
- Return the
url from the response to the user.
jq -n --rawfile html index.html \
'{html: $html, title: "My Page", subdomain: "my-page"}' \
| curl -sS -X POST https://yourwebs.cc/api/v1/pages \
-H "Authorization: Bearer $YOURWEBS_API_TOKEN" \
-H "Content-Type: application/json" \
--data-binary @-
Response (HTTP 201) is a page object — hand url back to the user:
{ "id": "01J0...", "subdomain": "my-page", "url": "https://my-page.yourwebs.app",
"title": "My Page", "size_bytes": 4096, "total_views": 0, "status": "active",
"created_at": 1747900800000, "updated_at": 1747900800000 }
title and subdomain are optional. The page is served at
https://<subdomain>.yourwebs.app. subdomain only takes effect with a token
(anonymous publishes get a random subdomain) and must be 3–32 chars, lowercase
a-z 0-9 -, no leading/trailing or doubled hyphen, not a reserved word. Omit it to
get a random subdomain.
Manage existing pages
All of these require the token.
curl -sS https://yourwebs.cc/api/v1/pages \
-H "Authorization: Bearer $YOURWEBS_API_TOKEN"
curl -sS https://yourwebs.cc/api/v1/pages/PAGE_ID \
-H "Authorization: Bearer $YOURWEBS_API_TOKEN"
jq -n --rawfile html index.html '{html: $html}' \
| curl -sS -X PUT https://yourwebs.cc/api/v1/pages/PAGE_ID \
-H "Authorization: Bearer $YOURWEBS_API_TOKEN" \
-H "Content-Type: application/json" --data-binary @-
curl -sS -X DELETE https://yourwebs.cc/api/v1/pages/PAGE_ID \
-H "Authorization: Bearer $YOURWEBS_API_TOKEN"
Quick reference
| Method | Path | Body | Token | Success |
|---|
| POST | /pages | { html, title?, subdomain? } | optional | 201 page |
| GET | /pages | — | required | 200 { pages: [...] } |
| GET | /pages/:id | — | required | 200 page |
| PUT | /pages/:id | { html } | required | 200 page |
| DELETE | /pages/:id | — | required | 200 { deleted: true } |
Constraints & errors
- HTML: UTF-8, contains
<!doctype html>/<html>, ≤ 1 MB (the raw HTML byte size,
matching size_bytes, not the JSON body). Else 400 invalid_html — fix the HTML,
don't retry unchanged.
400 subdomain_invalid: the subdomain breaks the format rules — fix it, don't
blindly retry. 409 subdomain_taken: it's valid but in use — pick another or omit.- Rate limits: 30 publishes/hour, 60 updates/hour. On
429 rate_limited, wait and
retry later rather than hammering — the window is hourly.
- Errors are
{ "error": { "code": "...", "message": "..." } }. Common codes:
bad_request (400), invalid_html (400), subdomain_invalid (400),
unauthorized / invalid_token (401), not_found (404),
subdomain_taken (409), rate_limited (429), no_subdomain_available (503).
- Anonymous pages (no token) auto-delete after 30 days and can't be claimed later;
publish with a token for anything you want to keep.
Full contract: see reference/api.md.
