Surface AI

Full details for one surface, including its edge_url and dashboard_url. To open the surface in the dashboard, open dashboard_url.

List every surface in the caller's organization, with each one's id, name, page URL, status and live_state. Use surface_get for one surface's dashboard link.

How a surface's test is doing: per variant, its sessions, sessions that reached the goal, conversion rate (rate_per_session) and win_probability — the bandit's estimated chance that variant is best. termination.should_terminate is the bandit's own signal that the test has a clear winner. Also all-time traffic per event. Results are recomputed hourly; before the first run, variants is empty and note says why. For sessions per day, use surface_traffic. Link the user to dashboard_url for charts.

The way to add a surface to a page, in one step: the content fields it swaps, the goals it optimizes, and the variants — with the integration bundle deployed. Returns the install guide for adding the snippet to that page. Ask the user to choose the fields, goals and variants first; the new_surface prompt walks through it. Prefer data-attribute selectors such as [data-surface-field="headline"], added to the page source. Variants go live as soon as the snippet is deployed. Counts toward the plan's surface limit; a name already used in the organization is rejected.

Sessions per day for a surface, as {date, sessions}. With no dates, every recorded day. For conversion and winners, use surface_results.

Change a surface's name, description, status, page URL or location; fields you leave out are unchanged. Returns the updated surface. ARCHIVED stops it serving; making it ACTIVE again counts toward the plan's surface limit. To change content, use the variant_ tools; to add a surface, surface_setup.

Add variants to a surface, as DRAFT; activate them with variant_set_status. Returns the surface's full variant list.

List every variant of a surface, the control included: each one's id, status, is_control and raw_contents (a JSON object of field key to value).

Make a variant the control of its segment — the baseline the others are measured against — replacing the current control. An archived variant can't be the control. Status is unchanged; use variant_set_status for that.

Activate, pause or archive a variant. Only active variants are served. To change which variant is the control, use variant_set_control.

Replace a draft variant's contents with the given object. Only drafts can be edited; to change a live variant, create a new one and archive the old.