# Publish HTML to YourWebs
Host a single self-contained HTML file on https://yourwebs.cc and get a public,
full-screen URL like https://my-page.yourwebs.app. This document teaches you, an
AI agent, how to publish and manage pages via the REST API.
API base: https://yourwebs.cc/api/v1
## Authentication
Every call except anonymous publish needs a bearer token (`ywb_...`), generated by
the user in the YourWebs dashboard at https://yourwebs.cc/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 it is unset, stop and ask the user
to set it:
```bash
export YOURWEBS_API_TOKEN="ywb_..." # generate it in the dashboard
```
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.
## Two domains, by design
- yourwebs.cc — the dashboard and the REST API.
- yourwebs.app — where pages are served. Subdomain `my-page` is served at
https://my-page.yourwebs.app.
## Publish a page
1. Write one self-contained HTML file (inline CSS/JS). UTF-8, contains
`` or ``, and ≤ 1 MB.
2. POST it as JSON. Use `jq` to escape the HTML — never hand-concatenate.
3. Return the `url` field from the response to the user.
```bash
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 is HTTP 201 with a page object; `url` is the public link. `title` and
`subdomain` are optional. `subdomain` only applies with a token, must be 3–32 chars,
lowercase `a-z 0-9 -`, no leading/trailing or doubled hyphen, not reserved. Omit it
for a random subdomain.
## Manage pages (all require the token)
```bash
# List your pages -> { "pages": [ ... ] }
curl -sS https://yourwebs.cc/api/v1/pages -H "Authorization: Bearer $YOURWEBS_API_TOKEN"
# Get one page
curl -sS https://yourwebs.cc/api/v1/pages/PAGE_ID -H "Authorization: Bearer $YOURWEBS_API_TOKEN"
# Replace a page's HTML (body: { html })
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 @-
# Delete a page -> { "deleted": true }
curl -sS -X DELETE https://yourwebs.cc/api/v1/pages/PAGE_ID -H "Authorization: Bearer $YOURWEBS_API_TOKEN"
```
## Constraints & errors
- HTML: UTF-8, contains ``/``, ≤ 1 MB (raw HTML bytes). Else
`400 invalid_html` — fix the HTML, don't retry unchanged.
- `400 subdomain_invalid`: fix the subdomain format. `409 subdomain_taken`: it's
valid but in use — pick another or omit for a random one.
- Rate limits: 30 publishes/hour, 60 updates/hour. On `429 rate_limited`, wait.
- Errors are `{ "error": { "code": "...", "message": "..." } }`.
- Anonymous pages (no token) auto-delete after 30 days; publish with a token to keep.
## Reusable install
A human can install this as a persistent skill across agents:
```bash
npx skills add sugarforever/yourwebs-skill
```