Create a NEW site (a 'roost') and return its public URL in one call. Returns `{ hatchId, slug, url, apex, promo, uploads? }` — show `url` to the user and remember `hatchId`. NEVER call hatch twice for the same site — use `convert` to rename, change tier, or set Promo, and `upload`/`deploy` for content updates.
Pick `apex` from the user's intent (homes / estate / land / wedding / events / agency / site / omit for theroost.dev). Do NOT invent other apexes.
Ways to call it:
• `html` (PREFERRED for n8n / a single review page) → one self-contained HTML string published at /. Do not also pass site/manifest/script.
• Omit `html`, `manifest`, `site`, and `script` → a placeholder page is published instantly.
• Pass `manifest` (file list with sizes) → returns presigned `uploads[]`; you PUT each file's bytes directly to its URL. PREFER this for any project with images, fonts, video, or more than a few KB of HTML.
• Pass `site` (inline files map) → small text-only sites only. File keys must be paths like `index.html` (n8n may send `index`; that is accepted as `index.html`).
• Pass `script` → advanced: full server-side code as one ES module (1.5 MiB max, text only — NEVER base64-embed binaries here).
Optional `promo` (boolean). `true` lists this hatch on the public carousel even when its tier would hide it, if the hatch is active, has a public slug, and is not expired, and forces the Powered By chip on. A password still keeps it off the carousel. `false` unmarks Promo and returns the normal carousel and chip rules. Omit `promo` to leave an existing hatch unchanged, or to create one under the normal rules. To change Promo later, call `convert` with `promo` — do not hatch again.
Do not send empty strings for optional fields (hatchId, preferredSlug, apex, html, site). Omit them.
View input schema
{
"type": "object",
"properties": {
"tier": {
"type": "string",
"enum": [
"free",
"forever"
],
"description": "`free` auto-expires (default 48h; override with `ttlSeconds`). In a paid Roost workspace, hatch stores `workspace` (still expires; not carousel-listed) even if you pass `free`. `forever` is a Pin (subscription slot or paid 1-year keep) — on this connector, hatch `free` then `checkout` with grant `publish`, or convert while subscription Pins remain."
},
"kind": {
"type": "string",
"enum": [
"site",
"run-report"
],
"description": "Artifact kind. Use `run-report` for agent observability / compliance run reports; default `site` for consumer sites."
},
"html": {
"type": "string",
"description": "Self-contained HTML document (inline CSS) published at /. Preferred for n8n and other AI tools that cannot pass nested site.files maps. Mutually exclusive with site, manifest, and script."
},
"ttlSeconds": {
"type": "integer",
"minimum": 3600,
"maximum": 604800,
"description": "Free-tier TTL in seconds (1h–7d). Default 172800 (48h). Ignored for `forever`."
},
"apex": {
"type": "string",
"enum": [
"theroost.dev",
"theroost.homes",
"theroost.estate",
"theroost.land",
"theroost.wedding",
"theroost.events",
"theroost.agency",
"theroost.site"
],
"description": "Specialty hostname apex for the live URL (`https://{slug}.{apex}`). Choose from user intent: theroost.homes (residential listing), theroost.estate (commercial/luxury), theroost.land (land/parcels), theroost.wedding (wedding RSVP), theroost.events (conference/meetup), theroost.agency (pitch/portfolio), theroost.site (generic short-lived niche). Omit for theroost.dev. Never pass theroost.rentals (reserved)."
},
"manifest": {
"type": "object",
"description": "PREFERRED for sites with assets. List every file you want served, with its byte size and optional MIME type. The response includes one presigned PUT URL per file; upload bytes directly via HTTP (e.g. `curl -T file.png -H 'Content-Type: image/png' \"$url\"`).",
"properties": {
"entry": {
"type": "string",
"description": "Document served at /. Default index.html"
},
"files": {
"type": "object",
"description": "Relative path → { size in bytes, optional contentType }.",
"additionalProperties": {
"type": "object",
"properties": {
"size": {
"type": "integer",
"minimum": 0
},
"contentType": {
"type": "string"
}
},
"required": [
"size"
]
}
}
},
"required": [
"files"
]
},
"site": {
"type": "object",
"description": "Inline file map. Suitable ONLY for small text-only sites (a handful of HTML/CSS files). For anything with images or binaries, use `manifest` instead.",
"properties": {
"entry": {
"type": "string",
"description": "Document served at /. Default index.html"
},
"files": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Relative path → contents. Text (UTF-8) for .html/.css/.js/.json/.svg; base64 (optionally prefixed `base64:`) for binary."
}
},
"required": [
"files"
]
},
"script": {
"type": "string",
"description": "Advanced: full server-side code as one ES module. Text only, 1.5 MiB hard limit. NEVER embed images/fonts/binaries here — use `manifest` instead."
},
"hatchId": {
"type": "string",
"description": "Optional id to reuse. Omit entirely to auto-generate. Do not send an empty string (n8n: leave this field unmapped). Lowercase letters, numbers, and hyphens only; 1–50 chars; must start and end alphanumeric."
},
"tenantId": {
"type": "string",
"description": "Legacy alias for `hatchId`."
},
"preferredSlug": {
"type": "string",
"description": "Hostname label. Omit for a friendly auto-name (e.g. swift-falcon-7a)."
},
"scriptMetadata": {
"type": "object",
"additionalProperties": true
},
"tosAcceptedAt": {
"type": "string",
"description": "ISO-8601 timestamp"
},
"workspaceId": {
"type": "string",
"description": "Workspace to hatch into (B2B). Omit when this connector is already paired to a workspace — the session supplies it. Do not hatch twice for a site that already exists in the workspace; call `list` first."
},
"policy": {
"type": "string",
"enum": [
"required",
"good_effort",
"optional"
],
"description": "HITL policy override for workspace-paired hatches. `optional` (default for a new Roost) does not open a review — call `await_decision` when you want one. `required` forks sibling `{slug}-vN` roosts when review is outstanding or approved. `good_effort` overwrites in place, supersedes open HITL, and auto-opens a fresh review. Inherits the stored workspace policy when omitted."
},
"webhookUrl": {
"type": "string",
"description": "Webhook for auto-opened HITL under workspace policy (see PARTNER-WEBHOOKS.md)."
},
"hitlTitle": {
"type": "string",
"description": "Modal title for auto-opened HITL."
},
"promo": {
"type": "boolean",
"description": "Optional Promo flag. `true` lists this hatch on the public carousel even when its tier would hide it, if the hatch is active, has a public slug, and is not expired, and forces the Powered By chip on. A password still keeps it off the carousel. `false` unmarks Promo and returns the normal carousel and chip rules."
}
},
"required": [
"tier"
]
}