Put a thing on the internet.
It'll be lovely.

What you can publish

Everything is one self-contained file. Paste it in, get a URL back, share it.

Quickstart

curl -X POST https://api.hostan.app/api/v1/deploy \
  -H "Content-Type: application/json" \
  -d '{"type": "markdown", "content": "# Notes\n\nEverything I remember."}'

# → 201 Created
{ "slug": "notes", "url": "https://sites.hostan.app/notes",
  "expires_at": "…seven days later…" }

Publish via AI agent

Add the MCP server once — Claude Code, Cursor or VS Code — and your agent gains deploy_asset: content in, live URL back, plus read_docs — the full agent instructions in-band. Free, no credential.

{
  "mcpServers": {
    "hostan": { "url": "https://api.hostan.app/mcp" }
  }
}

Limits

Deliberately small: fast to publish, easy to forget.

Over a limit: 429 with Retry-After: 60 — back off and retry. Platform full: 503 with a reason. Slugs are lowercase, hyphenated, 3–63 chars; a few names are reserved.

The model

Managed is one durable envelope: a project holds your pages and a private database, and everything shares its clock. Who gets what:

Workspaces & the dashboard

A workspace is the ownership boundary: it holds your projects and bills your plan. A credential authenticates a user, and that user's membership in a workspace carries the role they act with there — one account can belong to several workspaces, each with its own role.

Every account gets a personal workspace at sign-in (they own it); owners add teammates there or to a shared workspace. Authority is read live on each request, so removing a member takes effect immediately — no re-login and no token to re-mint.

Plans

A workspace holds exactly one plan, and the plan is what caps its projects. Upgrades are a payment, not a setting: a paid plan can never be asserted — it is granted when the payment provider confirms the subscription, and never before.

# owner floor: returns a hosted checkout URL for a human to open
POST /api/v1/workspaces/{id}/billing/checkout   →  { "url": "https://checkout.stripe.com/…" }

# the plan moves when the provider confirms the subscription — not before
GET  /api/v1/workspaces/{id}                    →  "plan": "pro"

# asserting a paid plan is refused, on purpose
PATCH /api/v1/workspaces/{id}  { "plan": "pro" }   →  403, naming the price

# the way out: the provider's own portal, where the owner cancels
POST /api/v1/workspaces/{id}/billing/portal     →  { "url": "https://billing.stripe.com/…" }

Cancel or let a subscription lapse and the workspace returns to free — your projects are never deleted. The plan is a limit, not a deletion: the workspace just cannot create more projects than the free allowance until it upgrades again. Both ends are dashboard buttons: Upgrade on a free card opens checkout, and Manage billing on a paid one opens the provider's portal — where the owner changes the card or cancels. Cancelling starts at the provider on purpose: the subscription ends there, and the workspace returns to free when the provider reports it.

manage_workspace { "action": "list" }                        # the workspaces you belong to, with your role
manage_workspace { "action": "get", "workspace": "acme" }
manage_workspace { "action": "add_member", "workspace": "acme",
                   "user_id": "usr_…", "role": "editor" }
manage_workspace { "action": "set_role", "workspace": "acme",
                   "user_id": "usr_…", "role": "viewer" }

# or over REST: GET /api/v1/workspaces (only your memberships)

Agents that connect over OAuth meet a consent page first: it names the client, the requested scope and the workspaces the client could act in. Deny cancels the connection (error=access_denied) and grants nothing. The token identifies the user, so a workspace created later is reachable without re-authorizing, and a revoked membership stops working on the very next request.

Build an app in three calls

# once: the credential on the hostan server entry
"hostan": { "url": "https://api.hostan.app/mcp",
            "headers": { "Authorization": "Bearer hstn_…" } }

manage_project  { "action": "create", "name": "Tasks" }
manage_backend  { "action": "create", "project_id": "0193…",
                  "ddl": "CREATE TABLE todos (id INTEGER PRIMARY KEY, title TEXT NOT NULL);" }
manage_frontend { "action": "create", "project_id": "0193…",
                  "type": "html", "content": "<h1>Hi</h1>", "requested_slug": "tasks-ui" }

Pages published after the backend exists get the hostan.db runtime automatically; earlier ones need one manage_frontend update. Evolve later with manage_backend update — pages pick up changes on their next call. For agent-managed edits, prefer the revision loop: create_revision publishes a change as an unlisted preview (your live page is untouched) and promote releases it — so nothing ships to the canonical URL until you explicitly say so, and a broken release rolls back with rollback.

hostan.db — actions, not SQL

Visitors never send SQL and never see a credential. Pages call named actions you define; raw SQL stays owner-only.

const res = await hostan.db.op("add_task", { title });
// res.rows[0].title — rows come back as objects

Visitor sign-in

Frontends can sign visitors in with Google or GitHub — run by the platform, no per-app OAuth setup, no session code. Pages read the visitor through the injected hostan.auth runtime, and each app owner picks which methods its frontends offer.

const user = hostan.auth.user();   // null, or { id, email?, name?, picture?, provider?, locale?, expiresAt? }
hostan.auth.login();                // redirect into sign-in, back to this page
hostan.auth.login('github');        // or force a specific method
hostan.auth.providers();            // the app's allowed sign-in methods
await hostan.auth.logout();         // revoke, then reload

Sign-in finishes on the platform's identity origin (auth.hostan.app) and returns the visitor to the origin they started from — the app's own subdomain, not a shared one. Sessions are per-frontend and project-scoped — signing in on one frontend never signs the visitor in on a sibling. Actions can bind the reserved :hostan_user_id / :hostan_user_email: the platform injects the signed-in visitor's identity, so rows are scoped per user with zero session code.

Real-time rooms

A backend with realtime: true gets one project-scoped WebSocket relay and an injected hostan.ws runtime: chat, presence, shared cursors, live dashboards and lightweight games — no external service.

const room = hostan.ws.connect('game-abc');

room.on('open', async () => reloadStateFromDb());
room.on('message', (env) => {          // env = { v, type, data, sender, room, ts }
  if (env.type === 'move') renderMove(env.data);
});
room.on('presence', (p) => updateCount(p.members));
room.on('close', () => showReconnecting());

room.send('move', { row: 1, column: 2 });
room.close();

Enable it at create (manage_backend with realtime: true) or flip it later with a standalone update {"realtime": true|false}. Frontends published after the capability was enabled carry the runtime; older pages need one republish. Rooms are strictly scoped: same backend + same room, never across backends, and the hostan:* event family belongs to the platform.

The relay is deliberately ephemeral: no history, no replay, no delivery receipts, no offline inbox. A restart ends all sockets — the runtime reconnects with capped backoff, and your app reloads authoritative state from hostan.db on open. Realtime is public (it is not authentication): keep the source of truth in the database, use :hostan_user_id actions for identity, and broadcast only transient state. Limits: 16 KiB frames, ~10 messages/second per socket, 100 sockets and 100 rooms per backend, 20 sockets per visitor IP.

Managed payments

Frontends can collect one-time payments through the platform's managed Stripe integration — hosted checkout, verified webhooks, and the entitlement verdict, all operated by the platform. No per-app keys, no webhook code, no amounts in the browser.

hostan.payments.checkout('price_…');   // redirect into hosted checkout
const pays = await hostan.payments.status();
// [{ price, status: 'paid', amount, currency, user_id?, email?, matched_by, created_at }]

Define prices with POST /api/v1/projects/{id}/payments/catalog ({product_name, label, amount, currency, recurring?} — amount in minor units) or the manage_payments MCP tool (add_price, catalog, deactivate_price, sessions). The returned price_… id is the only thing a page ever handles: the visitor picks a price, never an amount. A price flagged recurring bills as a monthly subscription; otherwise it is a one-time payment. The entitlement is granted on the first verified success webhook either way, and the platform enforces the lifecycle both ways — see below.

Checkout creates one hosted Stripe session and redirects the visitor; the verdict comes only from a signature-verified, deduplicated webhook that marks the session paid and materializes a row into the project's database. Reads through status() are authoritative platform state — the success redirect lands on a platform confirmation page at /<slug>/payments/success (canceled when the visitor abandons) and is UX, not proof. For signed-in visitors, payments match the platform user; an anonymous visitor is recognized only through this browser's checkout cookie (30 days) — a payment made without signing in is invisible from another browser or device. Each entry also carries matched_by ('user_id', 'email' or 'cookie', strongest wins) so an app can tell a platform-identity match from the email convenience: the email match is what lets a later sign-in claim an anonymous checkout, and since addresses get recycled, two different accounts sharing a provider-verified email both resolve paid on it — require matched_by === 'user_id' to trust platform identity only. The lifecycle is enforced both ways: a full refund or a terminated subscription revokes the entitlement (it disappears from status()), while a failed renewal is dunning — access continues while Stripe retries.

The platform also writes a reserved hostan_payments table into your database for JOINs and composability — a derived view you can query in your own actions, but treat status() as the hardened gate. The hostan_ table prefix is reserved platform-wide: your DDL may not create hostan_* tables. Where the platform has payments unconfigured, checkout answers 503 — the feature fails closed, it never half-exists.

Limits

Reliability

FAQ