Hatch

Create a NEW site (a 'roost') and return its public URL in one call. Returns `{ tenantId, slug, url, apex, uploads? }` — show `url` to the user and remember `tenantId`. NEVER call hatch twice for the …

Add or replace files on an EXISTING roost. Pass `tenantId` plus a `manifest` listing each file's path, size, and optional content type. Returns one presigned PUT URL per file — upload bytes directly v…

Resolve a roost by `slug` or `tenantId`. Returns a compact view `{ tenantId, slug, url, apex, tier, state, expiresAt, customDomain, galleryListed }`. Use this to recover state across turns when the us…

List every hatch in a workspace. Returns `{ workspaceId, name, count, hatches: [{ tenantId, slug, url, apex, kind, tier, state, expiresAt, createdAt }] }`. Use this when you lost tenantIds, before hat…

Atomically rename a roost's URL and/or change gallery listing. Pass `tenantId` plus at least one of `newPreferredSlug` (rename) or `galleryListed` (opt in/out of the Barnyard carousel on viberooster.c…

List VibeRooster features the user can pay for (Forever, coin packs, Workspace, Agentic Pro, …) with Stripe Price ids and amounts. Call this before `checkout` if you don't already know the grant. Retu…

Create a Stripe Checkout Session so the user can pay for a VibeRooster feature in this chat. Returns `{ checkoutUrl, sessionId, grant, amountCents }` — ALWAYS show checkoutUrl to the user (open it / p…

Long-poll a Checkout Session from `checkout` (~18s). Returns `{ status: open|complete|expired, grantApplied, roostUrl, tier }`. If still `open`, tell the user to finish paying at checkoutUrl and call …

Put a sign-in screen in front of a `forever` roost so visitors must authenticate. Pass `tenantId` plus an `action`: • `enable` with `mode: "password"` and a `password` → ONE shared site password (ever…

Issue a signed, expiring guest view URL for any tier (`?vt=…`). Use for private run reports without forever-tier password auth. Returns `{ url, viewToken, expiresAt }`.

Create a human-in-the-loop review on the live artifact. Default options: Approve / Request changes / Reject. Reviewers see a Review required chip → modal. Request changes is non-terminal: webhook or p…

After poll_decision returns status changes_requested, regenerate, then call this to reopen the same decision as pending_review for the next human round.

Long-poll (~20s) until the decision leaves pending_review. Returns changes_requested (regenerate + continue_decision), approved, rejected, timeout_exceeded, max_iterations_exceeded, or still pending_r…

Return the caller's current identity and tenant state. Never errors when unidentified — returns a pairing path instead. After poll_pairing completes, whoami with the same tenantId should show identifi…

Issue a fresh pairing code + URL (TTL 10 minutes) for claiming a hatch (tenantId) or authorizing an agent session in a workspace (workspaceId). Render pairingUrl as a QR for the Vibe Rooster app.

Poll for pairing completion (Device-Grant style). Waits up to ~20s for phone approval before returning. Statuses: pending / completed / expired / not_found. On completed, store sessionToken, refreshTo…

Renew a short-lived access token (~1h) using the refreshToken from poll_pairing. The grant (and refresh capability) lasts up to 7 days — after that, re-pair via get_pairing_code. Each refresh rotates …

Poll a pending Tier-2 phone approval. Returns the result once the owner approves or denies on their phone.

Replace the server-side code of an existing roost. Advanced — most agents should use `upload` (for static files) or `convert` (for renames) instead. Pass `tenantId`, `workerName`, and a full ES module…

Scaffold an HTML run report (what I did / inferred / about to do / confidence / alternatives) and hatch it as a live URL.