Skip to content

Sites ​

Sites are website instances belonging to a team. A team can have many sites. Owners, admins, and developers can create and manage sites.

With or without a brand ​

A site can optionally link a Warp brand (brandSlug):

  • With brand — live app on sites.joai.ai at /{teamSlug}/{brandSlug}
  • Without brand — site record only (e.g. agency portfolio / external websites), with optional client contact, metrics source/resource, and monthly reports

Optional type:

  • undefined (default) — generic website record
  • shop — storefront URL used as the post-checkout return address (requires url; one shop site per team, including disabled; set type to undefined before assigning shop to another site; brand-backed sites cannot be shops). Guest thank-you / order payloads include this site when configured — see Shop.

Create without a brand from Sites → Add → Website, or via POST /v1/sites / warp joai/site-create with team + name (optional url, type). Provisioning a brand still creates/links a brand-backed site (joai/site-provision).

Install Sites under Team settings → Apps, then open Sites in the sidebar (/sites).

Overview ​

  • Many sites per team (slug is unique per team)
  • Brand-backed sites: live URL on sites.joai.ai
  • Brandless sites: portfolio records, contact linkage, metrics source + resource, optional monthly report
  • Optional custom domain (premium) for any site, brand-backed or brandless
  • Edit CMS content and elements on brand-backed sites
  • Same Warps power the browser UI and agent MCP calls — no duplicate logic
  • Pair with Appointments for booking brands, Forms for intake, Contracts for on-chain apps

URL structure ​

Brand-backed sites (production):

https://sites.joai.ai/{teamSlug}/{brandSlug}
https://sites.joai.ai/{teamSlug}/{brandSlug}/configure
EnvironmentHost
Mainnetsites.joai.ai
Testnettestnet-sites.joai.ai
Devnetdevnet-sites.joai.ai

Optional custom domain (premium, any site). Brand-backed sites point a CNAME at the Sites host for your environment. Brandless / externally hosted sites keep their own hosting; verify ownership with the TXT record, or automatically via the HTTP .well-known/joai-site-verification route when the host implements it (the shared clients host does). See Public surfaces.

Brandless sites are not published on sites.joai.ai.

In the app ​

Site manager (/sites) ​

  1. Install Sites
  2. Open Sites
  3. Add → Website (name, optional URL + type) for portfolio / external / shop sites, or Add → Live app for Warp brands
  4. Per site:
    • Toggle enabled
    • Open the edit page (pen icon) for reporting, metrics, monthly reports, custom domain, and online status
    • When uptime monitoring is enabled, the Online status badge links to the public status page (/uptime/{siteId}). An optional check path such as /health makes monitoring request that path while the status page continues to show the main site URL
    • Set type to Shop when this URL is the storefront customers should return to after checkout
    • Link a contact and a metrics source + resource (same pair as metrics-query):
      • JoAi Analytics — native, cookie-free web traffic for JoAi-hosted or external sites. Use source analytics, add the public hostnames that may send data, and let JoAi create the site key. JoAi-hosted sites add the tracker automatically; external sites use the install snippet in Sites. It reports daily unique visitors and page views without storing cookies, browser storage, query strings, page referrers, raw IP addresses, or user agents. Reporting reads daily rollups rather than raw traffic.
      • Cloudflare — connect under Cloudflare, use source cloudflare and the zone tag as resource
      • Google Search Console — connect under Google Search Console, use source google_search_console and a property URL (sc-domain:example.com or https://example.com/) as resource. Reports search clicks/impressions, not site analytics visitors.
      • Instagram — for Social Media insights (not Sites monthly reports); use query_metrics with source instagram and the numeric account id. See Instagram.
    • Transfer to another team (site settings): pick a team where you have site-manage permission and confirm. The site keeps its slug, URL, custom domain, analytics, uptime, and monthly report settings. The linked contact is remapped by email when the target team has a matching contact, otherwise detached, and the custom domain is re-verified under the target team. The transfer fails if the site slug or brand slug is already used there.
    • Optionally enable monthly report. Native JoAi Analytics requires no third-party integration. For Cloudflare or Google Search Console, a missing integration returns channel_not_configured (422) so the Sites UI opens the matching setup dialog, and chat/MCP can call settings-integration-open then retry. On the 1st of each month the platform job creates an update artifact with metric blocks for the previous month and runs artifact-deliver (draft → approve / auto-mode). The email is written for business owners in plain language (no CTR/impression jargon) and contains the full report itself, so no separate public artifact link is added. The report still shows under Artifacts and Contact → Deliveries.
  5. Per brand-backed site:
    • Add brand → provision missing brands, then copy/open the public URL
  6. Set or verify the custom domain in the site edit page: brand-backed sites get CNAME instructions; brandless / external sites verify via TXT or HTTP. The section always shows its state (none, pending, verified, or upgrade required) instead of disappearing. Verified domains are re-checked weekly: failed checks show in the site settings and notify the team, and the domain is marked unverified after three consecutive failures.
  7. Open Content (/sites/content) for CMS pages and elements

Content and elements (/sites/content) ​

From Sites → Content:

  1. Create content with a field schema (structured page data)
  2. For image and media fields, choose an existing image from the team media library or upload one directly from the field. The selected media URL is stored with the content record.
  3. Edit drafts; preview before going live. An explicitly approved content update can also save and publish in one action.
  4. Publish or rollback to a previous version
  5. Manage elements and variations (reusable blocks; generate variations when supported)

These map 1:1 to the Sites MCP tools below.

When an agent proposes content create/update/publish/restore, pending actions show a structured approval card: field-level before/after for edits (with expandable diffs for long text and media thumbs for image/media fields), and name/slug/version context for publish and restore — not raw JSON patches.

Site create/update/provision and element create/update/delete (plus variation generate/update/delete) use the same style of approval cards: site name/URL/type/contact/metrics diffs, and element description/prompt/media/variation previews with MediaPreview thumbs when media IDs are present.

How routes work (brand config) ​

Brand configs in the Warps repository map URL paths to Warps:

json
{
  "enabled": true,
  "auth": false,
  "indexPath": "/",
  "routes": [
    { "path": "/", "warp": "book", "label": { "en": "Book" }, "nav": true },
    { "path": "/configure", "warp": "configure", "label": { "en": "Settings" }, "nav": false }
  ]
}

Warps can be standard collect/action forms or Warp UI (ChatApps) embedded with the MCP App Bridge (calendars, wizards, multi-step flows).

Team identity (name, logo, colors) comes from team / brand settings automatically.

Authentication ​

When auth: true is set in the brand config, visitors sign in with JoAi branding. After login, the session token is passed to Warp actions for gated data. New users can sign up on the sign-in page; wallet and agent can be provisioned on first visit when required by the flow.

AI-native by design ​

Every Warp behind a route is callable by agents via MCP / execute. A booking page that works in the browser also works when an agent books on the user’s behalf.

From smart contract to app ​

  1. Deploy a contract → generate Warps from ABI
  2. Tune labels / hidden fields / gas
  3. Define brand.ts site routes
  4. Publish the brand
  5. Enable the site for the team → live at sites.joai.ai/{team}/{brand}

See Contracts and ChatApps.

For agents (MCP) ​

Requires the Sites app.

ToolPurpose
list_sites / create_site / update_sitePortfolio sites; optional type=shop + url for checkout return; set contact + metrics; monthlyReport opts into the 1st-of-month job (does not send now)
transfer_siteMove a site to another team you manage; re-verifies the custom domain and remaps or detaches the linked contact
query_metricsRead Cloudflare, Google Search Console, or Instagram metrics for a period
list_contents / get_content / create_content / update_contentCMS pages; update_content saves a draft unless its approved publish option is set
preview_content / publish_content / rollback_contentLifecycle
list_content_versionsVersion history
list_elements / create_element / update_element / delete_elementElements
list_element_variations / generate_element_variation / update_element_variation / delete_element_variationVariations

Related Warps: joai/site-list, joai/site-create, joai/site-update, joai/site-transfer, joai/site-provision, joai/metrics-query. When monthlyReport is on, the platform job creates an update artifact and runs artifact-deliver on the 1st.

Live schemas: tools/list. See MCP and SKILL.md.

Building your own brand ​

  1. Add warps/{brand}/ in the Warps repository
  2. Create brand.ts with a site config
  3. Publish the brand catalog
  4. Teams enable the site from Sites settings

See the contributor docs in the Warps repository.