# hyperux API · the context and delivery contract (v0, 2026-10-08)

> **Para el operador:** este contrato es único para los tres clientes del motor: los devs de afuera, localmkr y Mansos.
> Dice qué entra (el contexto) y qué sale (la entrega). Está en inglés porque es la documentación que van a leer los
> devs. La razón de cada decisión está en `../BASES.md` §8, y el estado en `../PLAN_MAESTRO_2026-10-08.md`.

hyperux turns **context** into a **delivery**:

- **Pre-built production sections + a design system → a live workspace with variants, in seconds.**
- Layout costs no model tokens. Assembly is deterministic and takes milliseconds.
- The only model calls are the short ones that read the source and write the copy.

Every field below is marked **v0** (works today) or **pending**. A pending field is accepted, and the response says,
under `notes`, what it did instead. **Nothing is silently ignored.**

## 1. Context (what you send)

`POST /v1/redesign` (start from something that exists) and `POST /v1/new` (start from an idea) take the same body:

```jsonc
{
  "source": {
    "url": "https://example.com",       // redesign · v0
    "html": "<!doctype html>…",         // redesign · v0: a page this server cannot open (localhost); read with no scripts and no network
    "base_url": "http://localhost:3000/",  // optional, with html: where that page lives
    "idea": "A booking app for dog groomers in Austin"   // new · v0
  },
  "context": {
    "brief": "What it is, who it is for, what the page must achieve",   // v0: read with the source; it wins over guesses
    "name": "Pawsome", "city": "Austin", "trade": "dog grooming",     // v0: these win over what the source says
    "data": ["contact form", "bookings", "products", "login"],          // pending (H6): the backend each section needs
    "pages": ["/"]                                                      // v0: the home page; more pages are pending
  },
  "design": {
    "variants": 4,                       // v0: 1–8 looks of the same page, chosen for this content (default 4)
    "styles": ["linear.app", "stripe"],  // v0: or name the looks (ids from GET /v1/styles)
    "design_md": "---\nname: …"          // pending (engine): your own DESIGN.md (Google/Stitch format)
  },
  "output": {
    "format": "html",                    // v0: html · pending: react (TSX + Tailwind)
    "lang": "auto"                       // v0: the copy follows the source's language; pending: force "en" / "es"
  }
}
```

**The answer** is `202 Accepted`, with:

```json
{ "workspace": { "id": "ws-…", "status": "building", "api": "/v1/workspaces/ws-…", "view": "/w/ws-…" } }
```

## 2. Delivery (what you get back)

`GET /v1/workspaces/{id}` returns:

```jsonc
{
  "id": "ws-…", "kind": "redesign", "status": "building | ready | failed", "step": "read | plan | design | assemble | capture | done",
  "source": { "url": "…" }, "created": "2026-10-08T…Z", "ms": 13200,
  "variants": [
    { "style": "linear.app", "mode": "dark",
      "view": "/w/ws-…/v/linear.app",                                   // the live page
      "code": "/v1/workspaces/ws-…/code?variant=linear.app",             // the HTML to take
      "screenshot": "/v1/workspaces/ws-…/screenshot?variant=linear.app&width=1440" }
  ],
  "sections": [ { "section": "hero", "kind": "hero" } ],
  "notes": ["output.format 'react' is pending; delivered html"],
  "error": null
}
```

**The other routes:**

| Route | What it returns |
|---|---|
| `GET /v1/workspaces/{id}/code?variant=&format=html` | The finished page, one self-contained HTML document (Tailwind CDN, CSS variables for the design tokens, fonts), with no editor markers. Add `&download=1` to save it as a file. `format=react` answers `501` until the engine ships it |
| `GET /v1/workspaces/{id}/screenshot?variant=&width=1440\|390&full=1` | A PNG of that variant at that width. It is how an agent looks at the result without opening a browser |
| `GET /v1/sections?kind=&mode=&family=&q=&limit=&offset=` | The library: every usable section, with its kind, ground (light/dark), type (sans/serif), the business families it suits and its reference |
| `GET /v1/sections/kinds` | The kinds, with how many sections each has |
| `GET /v1/styles?mode=` | The looks the engine can paint today |
| `GET /w/{id}` | The live workspace for a person: every variant side by side, zoom, open and take the code |
| `POST /v1/mcp` | The same API as an MCP server (Streamable HTTP, JSON-RPC 2.0). Tools: `hyperux_new` and `hyperux_redesign` (they wait for the result), `hyperux_workspace`, `hyperux_screenshot` (returns the image), `hyperux_code`, `hyperux_style`, `hyperux_swap`, `hyperux_qa`, `hyperux_backend`, `hyperux_host`, `hyperux_sections`, `hyperux_styles`. In Claude Code: `claude mcp add --transport http hyperux <origin>/v1/mcp` |
| `POST /v1/workspaces/{id}/variants/{n}/style` `{style}` · `…/swap` `{section}` · `GET …/qa` | Repaint a variant in another look, swap one section for another of the same kind (instant, no model), and measure it at 1440 and 390 (sideways scroll, past the edge, broken images, low contrast). In the MCP: `hyperux_style`, `hyperux_swap`, `hyperux_qa` |
| `POST /v1/workspaces/{id}/variants/{n}/host` · `GET …/host` · `DELETE …/host` | Puts a variant online at `{id}-{n}.hyperux.page` for 7 days, to share it or open it on a phone. Its forms work there, it is not indexed, and later changes to the variant (style, swap) show up at the same address. `GET` says where it is, until when, and its views and form sends. In the MCP: `hyperux_host` |
| `GET /v1/workspaces/{id}/backend?variant=&stack=cloudflare\|next` | The backend the page's forms need, as files for your stack. In the MCP: `hyperux_backend` |
| `GET /v1/agents.md` | How an agent uses hyperux over HTTP, without installing anything |

## 3. Access and limits (v0)

- **Reading is open:** the workspace, its code, its screenshots, the library and the workspace view. Workspace ids are
  unguessable.
- **The code you take is yours:** no hyperux badge, no hyperux scripts, no editor attributes, and `<html lang>` follows the language of the copy.
- **Generating needs a key** (`Authorization: Bearer …`, from `HYPERUX_V1_KEYS`), or a call from the machine itself.
  Accounts, free credits and plans come in H4.
- **At most 3 generations run at once.** The next one answers `429` with `retry_after`.
- **Workspaces are temporary** while plans don't exist. They live where the server runs. A hosted variant lives 7 days
  on `hyperux.page` after its last change; take the code to keep it.

## 4. What the three clients send

| Client | Its source | Its context | What it takes |
|---|---|---|---|
| A dev's agent | the URL, or the idea | the brief from its repo and conversation | the code of the chosen variant, and the screenshots for QA |
| localmkr | the business's old site, or what the owner said | the business facts mkr gathered | the page, edited and published by localmkr |
| Mansos | Brain's plan | the product, its sitemap and its data | pages and backend for every route (pending: H6) |

## 5. Pending, in order

| What | Who | Where |
|---|---|---|
| React output | Mac (engine) | `PEDIDO_MAC.md` v3 #3 |
| Forced `lang` and neutral English default copy | Mac (engine) | v3 #1–#2 |
| Your own DESIGN.md | Mac (engine) | v3 #4 |
| SaaS sections (pricing, login, app shell, tables) | Mac (library) | v3 #5. Today's page grammar is a business site: hero, services, steps, gallery, FAQ, contact, closing call |
| Hosting on `hyperux.page` | PC | H1 |
| The canvas (the human view of a workspace, beyond the side-by-side view) | PC | H3 |
| The canvas | PC | H3 |
| Accounts and credits | PC | H4 |
| Backend from `context.data` | PC + Mac | H6 |