Tools

Every tool takes a surface_id — never a content source id. Results are scoped to the key holder's workspace: another workspace's surface reads as not found. No tool deletes anything; archive instead, or use the dashboard.

surface_listCopy Anchor Link

List surfaces. Every surface in the key holder's organization.

No arguments.

Returns { surfaces: Surface[] }

surface_getCopy Anchor Link

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

Returns { surface: Surface, dashboard_url: string }

Errors SURFACE_NOT_FOUND, INVALID_ARGUMENTS

{
  "surface_id": 52
}

surface_createCopy Anchor Link

Create a surface. Creates the surface and its content source. Add content with variant_create.

Returns { surface: Surface, dashboard_url: string }

Errors PLAN_LIMIT_REACHED, INVALID_ARGUMENTS

{
  "name": "Homepage hero",
  "page_url": "https://example.com/",
  "paradigm": "VARIANT_SELECTION"
}

surface_setupCopy Anchor Link

Set up a surface on a page. One step from a page to a deployed surface: the fields variants replace, the goals to optimize, and the variants, with the integration bundle built and deployed. Variants are active; nothing shows until the snippet is on the page. The setup_surface prompt walks an agent through it.

Returns { surface: Surface, dashboard_url: string, variants: Variant[], events: string[], install_guide: string }

Errors PLAN_LIMIT_REACHED, INVALID_ARGUMENTS, SETUP_FAILED

{
  "name": "Pricing hero",
  "page_url": "https://example.com/pricing",
  "fields": [
    {
      "key": "headline",
      "selector": "[data-surface-field=\"headline\"]",
      "value_type": "text"
    }
  ],
  "goals": [
    {
      "name": "Book a demo",
      "selector": "[data-surface-goal=\"book_demo\"]",
      "dom_event": "click"
    }
  ],
  "variants": [
    {
      "contents": {
        "headline": "Pricing"
      },
      "is_control": true
    },
    {
      "contents": {
        "headline": "Plans that pay for themselves"
      }
    }
  ]
}

surface_updateCopy Anchor Link

Update a surface. Change one or more fields. Only the fields listed here are writable.

Returns { surface: Surface }

Errors SURFACE_NOT_FOUND, INVALID_ARGUMENTS — also when no field is given

{
  "surface_id": 52,
  "description": "Updated from Claude Code"
}

variant_listCopy Anchor Link

List variants. The content variants a surface serves.

Returns { variants: Variant[] }

Errors SURFACE_NOT_FOUND

{
  "surface_id": 52
}

variant_createCopy Anchor Link

Create variants. Adds variants as DRAFT. Fields other than is_control and segment_id are stored as the variant's content.

Returns { variants: Variant[] } — the surface's full list

Errors MULTI_SURFACE_SOURCE, SURFACE_NOT_FOUND, INVALID_ARGUMENTS

{
  "surface_id": 52,
  "variants": [
    {
      "headline": "Ship faster"
    },
    {
      "headline": "Launch today"
    }
  ]
}

variant_updateCopy Anchor Link

Edit a draft variant. Replace a draft variant's contents. Only drafts can be edited.

Returns { variant: Variant }

Errors VARIANT_NOT_FOUND, INVALID_ARGUMENTS — e.g. the variant isn't a draft

{
  "surface_id": 52,
  "variant_id": 300,
  "contents": {
    "headline": "Ship faster"
  }
}

variant_set_statusCopy Anchor Link

Set a variant's status. Activate, pause or archive a variant. Only active variants are served. Same rules as the dashboard.

Returns { variant: Variant }

Errors VARIANT_NOT_FOUND, MULTI_SURFACE_SOURCE, INVALID_ARGUMENTS

{
  "surface_id": 52,
  "variant_id": 300,
  "status": "ACTIVE"
}

variant_set_controlCopy Anchor Link

Set the control variant. Make a variant the control of its segment, replacing the current control.

Returns { variant: Variant }

Errors VARIANT_NOT_FOUND, INVALID_ARGUMENTS — archived target, or no control to swap

{
  "surface_id": 52,
  "variant_id": 301
}