API Reference

Install as an agent skill

Works with Cursor, Claude Code, Codex, Windsurf, OpenClaw, and any agent supporting the Skills protocol.

npx skills add gui-now/skills --skill gui-now -g

Pick your path

Use the first one that fits. They all hit the same endpoint.

Agents should prefer the CLI over hand-writing HTTP — embedding a full HTML document inside a JSON string by hand is where these calls usually go wrong. See llms.txt.

CLI

Zero dependencies, Node 18+. Pipe HTML in, get a URL back.

npm install -g gui-now

Or run it without installing:

npx gui-now push index.html

Usage

gui push index.html                       # push a file
cat index.html | gui push                 # or pipe from stdin
gui push index.html --title "Dashboard"   # name it
gui push --markdown README.md             # render markdown
gui push index.html --open                # open in a browser after
gui push index.html --json                # full JSON response
gui push index.html --expires 7d          # Pro: longer expiry
gui open abc123                           # open an existing canvas

Options

Pro API key

Set it in the environment to lift the rate limit from 5/hr to 100/hr and unlock longer expiry:

export GUI_NOW_API_KEY=YOUR_PRO_KEY

Published as gui-now on npm. Note the JS SDK is a different package, gui-now-sdk.

Base URL

https://gui.now/api

Create a new canvas. Returns a shareable URL. Accepts HTML, Markdown, or structured components.

Request Body

* One of html or markdown is required. Use <gui-*> component tags directly in either format.

Pro API Key

Pass as a header to unlock Pro limits:

x-api-key: YOUR_PRO_KEY

Examples

curl -X POST https://gui.now/api/canvas \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "My Dashboard",
    "html": "<h1 style=\"color:white\">Hello World</h1>"
  }'

curl -X POST https://gui.now/api/canvas \
  -H 'Content-Type: application/json' \
  -d '{
    "markdown": "# Sprint Report\n\nShipped **3 features** this week.",
    "title": "Sprint Report"
  }'

curl -X POST https://gui.now/api/canvas \
  -H 'Content-Type: application/json' \
  -d '{
    "html": "<gui-grid columns=\"2\"><gui-card title=\"Revenue\" value=\"$12,450\" change=\"+8.2%\"></gui-card><gui-chart type=\"bar\" data=\'[{\"label\":\"Q1\",\"value\":42}]\'></gui-chart></gui-grid>",
    "title": "Dashboard"
  }'

curl -X POST https://gui.now/api/canvas \
  -H 'Content-Type: application/json' \
  -d '{
    "html": "<h1>Default view</h1>",
    "frames": [
      {"html": "<h1 style=\"color:red\">Option A</h1>", "label": "Red"},
      {"html": "<h1 style=\"color:blue\">Option B</h1>", "label": "Blue"}
    ]
  }'

Response

{
  "id": "abc123xyz",
  "url": "https://gui.now/abc123xyz",
  "edit_token": "tok_...",
  "expires_at": "2026-02-28T16:00:00Z",
  "pro": false,
  "format": "html"
}

Create a Mermaid diagram. Rendered as a pannable, zoomable SVG. Supports flowcharts, sequence, class, state, ER, gantt, pie, mindmap, timeline.

curl -X POST https://gui.now/api/flow \
  -H 'Content-Type: application/json' \
  -d '{
    "mermaid": "graph TD\n  A[Start] --> B{Decision}\n  B -->|Yes| C[Do it]\n  B -->|No| D[Skip]",
    "title": "My Flow"
  }'

Update an existing canvas. Requires edit_token. All viewers see changes live via SSE. Free: 3 edits. Pro: unlimited.

Headers

Body fields

curl -X PUT https://gui.now/api/canvas/abc123xyz \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer tok_...' \
  -d '{"html": "<h1>Updated!</h1>"}'

Extend canvas expiry by 24 hours from now.

curl -X POST https://gui.now/api/canvas/abc123xyz/extend

Server-Sent Events stream. Receive real-time updates when canvas content changes.

const source = new EventSource(
  'https://gui.now/api/canvas/abc123xyz/events'
);

source.onmessage = (e) => {
  const data = JSON.parse(e.data);
  if (data.type === 'update') {
    // data.html, data.title, data.frames
  }
};

Events: connected (on subscribe), update (content changed).

Component Library

Auto-injected into every canvas. No imports needed — just use the HTML tags.

<gui-chart type="bar" data='[{"label":"Q1","value":42},{"label":"Q2","value":58}]'></gui-chart>

<gui-table data='[{"name":"Alice","role":"Eng"},{"name":"Bob","role":"PM"}]'></gui-table>

<gui-card title="Users" value="12,847" change="+12.3%"></gui-card>

<gui-code language="python">def hello(): print("world")</gui-code>

<gui-kanban columns='[{"title":"Todo","items":["Task 1"]},{"title":"Done","items":["Task 2"]}]'></gui-kanban>

<gui-timeline data='[{"date":"Mar 1","title":"Launch"}]'></gui-timeline>

<gui-form fields='[{"name":"email","type":"email","label":"Email"}]'></gui-form>

<gui-grid columns="3">...</gui-grid>

* Pie and radar charts require Pro. Form inputs sync across all viewers automatically.

Built-in Features

Every canvas automatically gets:

Limits

Free tier requires no account or API key. Rate limited by IP address.

SDKs

For building canvases from inside an application. To create one from a terminal, use the CLI.

npm install gui-now-sdk

import { createGui } from 'gui-now-sdk'
const gui = createGui()

const canvas = await gui.create({ html: '<h1>Hello</h1>' })
console.log(canvas.url)

await gui.update(canvas.id, canvas.edit_token, { html: '<h1>v2</h1>' })

pip install gui-now

from guinow import GuiNowClient

client = GuiNowClient()
canvas = client.create(
    html="<h1>Hello</h1>",
    title="My Dashboard",
)
print(canvas.url)

client.update(canvas.id, canvas.edit_token, html="<h1>v2</h1>")

For AI agents

Point your agent at these files to teach it GUI: