sitectrl

The connected sitectrl account: email, plan status, free-site slot, and credit balance.

{
  "type": "object",
  "properties": {}
}

List the user's sitectrl sites with their live URLs and hosting platform.

{
  "type": "object",
  "properties": {}
}

Details for one site: live URL, draft URL, status.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "description": "The site's slug from list_sites."
    }
  },
  "required": [
    "slug"
  ]
}

Build a brand-new hosted website from a plain-language description. RETURNS IMMEDIATELY with status 'building' — the site takes about 2-3 minutes and is NOT ready when this returns. Tell the user where it will be (expected_url) and poll get_build_status with the returned claim_token. NEVER call create_site a second time for the same site: each call builds another one. Works WITHOUT signing in: an unauthenticated call builds a guest site and returns a claim_url — the user signs up free (no card) at that link to keep it; unclaimed guest sites are deleted after 72 hours. Signed in, the site lands directly on the connected account (free tier: one site, no card).

{
  "type": "object",
  "properties": {
    "site_name": {
      "type": "string",
      "description": "Short human name for the site, e.g. 'Whitney Apparel'."
    },
    "description": {
      "type": "string",
      "minLength": 12,
      "description": "What the site is for. MINIMUM 12 CHARACTERS — a bare 'bike shop' is rejected. Say what the business is, where it is, and what the site should include; the AI builds directly from this, so more detail means a better first result. Good: 'Oak Barrel Coffee, a small-batch roaster in Turlock CA — our story, three coffees with tasting notes and prices, and a contact form.' If the user was vague, ask them one question before calling this rather than sending two words."
    },
    "template": {
      "type": "string",
      "enum": [
        "local-services",
        "restaurant",
        "shop",
        "portfolio",
        "classes",
        "community"
      ],
      "description": "Starting template (guest builds; default local-services)."
    },
    "contact_email": {
      "type": "string",
      "description": "Optional, guest builds only: the user's email — we send the site link and a reminder before the unclaimed site expires."
    }
  },
  "required": [
    "site_name",
    "description"
  ]
}

Check whether a site started by create_site has finished. Pass the claim_token create_site returned. Works WITHOUT signing in. Poll this every 30-60 seconds rather than calling create_site again — a second create_site call builds a SECOND site.

{
  "type": "object",
  "properties": {
    "claim_token": {
      "type": "string",
      "description": "The claim_token from create_site."
    }
  },
  "required": [
    "claim_token"
  ]
}

Ask sitectrl's AI editor to change an existing site ('add a contact page', 'make the hero darker'). Edits land in the site's draft; the first build of a brand-new site goes straight live. Returns what changed plus the draft URL.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string"
    },
    "instruction": {
      "type": "string",
      "description": "The change to make, in plain language."
    }
  },
  "required": [
    "slug",
    "instruction"
  ]
}

Push files (HTML/CSS/JS/images) into a site's DRAFT — use this when YOU are writing the code yourself instead of asking sitectrl's AI. Text files go in 'content'; binary files (images/fonts) in 'content_base64'. Max 40 files/call, 2 MB/file. Keep the <script defer src="sc-track.js"></script> include on every HTML page (the site's built-in private analytics — publish re-adds it if missing). Use clearly-marked placeholder contact info unless the user provided real details. For working forms, POST to /_sc/form/submit with a hidden _form name field — submissions reach the owner's dashboard + email (never use mailto:). Every HTML file is checked before it's written (DOCTYPE, charset, and any invariant this site has declared) — a file that fails is refused and comes back in 'refused' with what's wrong and the exact fix; other files in the same call still write. Follow with publish_site to go live.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string"
    },
    "files": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "description": "Relative path in the site, e.g. index.html or css/style.css"
          },
          "content": {
            "type": "string"
          },
          "content_base64": {
            "type": "string"
          }
        },
        "required": [
          "path"
        ]
      }
    }
  },
  "required": [
    "slug",
    "files"
  ]
}

List the files in a site's draft tree (paths + sizes).

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string"
    }
  },
  "required": [
    "slug"
  ]
}

Read one file from a site's draft tree (text, or base64 for binary; 512 KB cap).

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string"
    },
    "path": {
      "type": "string"
    }
  },
  "required": [
    "slug",
    "path"
  ]
}

Publish the site's draft to the LIVE site (hosted sites). A snapshot of the previous live version is taken first, so it's undoable.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string"
    }
  },
  "required": [
    "slug"
  ]
}

Insert a component from the site's shared library into one or more existing pages, INSTEAD of hand-writing the markup yourself — the classes are already styled and themed to this site's colours. Choices: sc-page-title (the page's one <h1>), sc-gallery (cross-fading photo reel — needs 'images'), sc-info-tiles (title + picture + text sections — needs 'tiles'), sc-instructions (numbered/titled steps, optionally with a button each — needs 'tiles'), sc-event (one dated thing: a class, a session, an opening — needs 'title'), sc-btn (a link styled as a button — needs 'label'). NOT offered: sc-header/sc-footer (the site's own shell already emits those) or sc-hero (placed once, on the home page, by the site's own build). 'anchor' says where it goes: {"type": "heading", "value": "<text on the page>", "position": "after"} (default), {"type": "id", "value": "<element id>", "position": "after"}, {"type": "main_end"} (append at the end of the page), or {"type": "replace", "value": "<class of an existing sc-* block>"}. 'pages' is "all" or a list of paths from list_site_files. A page whose anchor doesn't match comes back in 'findings' with what's wrong and the fix — other pages in the same call still get the component. Follow with publish_site.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string"
    },
    "name": {
      "type": "string",
      "enum": [
        "sc-page-title",
        "sc-gallery",
        "sc-info-tiles",
        "sc-instructions",
        "sc-event",
        "sc-btn"
      ]
    },
    "pages": {
      "oneOf": [
        {
          "type": "string",
          "enum": [
            "all"
          ]
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          },
          "minItems": 1
        }
      ],
      "description": "\"all\", or an array of page paths, e.g. [\"index.html\", \"about.html\"]"
    },
    "anchor": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "heading",
            "id",
            "main_end",
            "replace"
          ]
        },
        "value": {
          "type": "string",
          "description": "heading text / element id / class to replace — not used for main_end"
        },
        "position": {
          "type": "string",
          "enum": [
            "before",
            "after"
          ],
          "description": "for heading/id anchors, default after"
        }
      },
      "required": [
        "type"
      ]
    },
    "fields": {
      "type": "object",
      "description": "Component-specific content. sc-page-title: {text, eyebrow?}. sc-gallery: {images: [{src, alt}]}. sc-info-tiles: {tiles: [{title, img?, alt?, text}]}. sc-instructions: {title?, intro?, tiles: [{title?, body, img?, alt?, button?: [label, href]}]}. sc-event: {title, img?, meta?: [{label, value}], desc?, rsvp_href?, rsvp_label?}. sc-btn: {label, href}."
    }
  },
  "required": [
    "slug",
    "name",
    "anchor",
    "fields"
  ]
}

Search real domain availability + prices (com/net/org/co/io/site and more). Available results include a purchase_url — hand it to the USER to complete checkout; the connector never spends money. Purchased domains connect to their sites in one click.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Domain or name to check, e.g. 'sierratrailcoffee.com'."
    }
  },
  "required": [
    "query"
  ]
}

The site's private first-party traffic: pageviews/visitors/sessions/clicks totals, top pages, referrers, devices. Windows: 24h, 7d, 30d.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string"
    },
    "window": {
      "type": "string",
      "enum": [
        "24h",
        "7d",
        "30d"
      ]
    }
  },
  "required": [
    "slug"
  ]
}