MCP tool reference

AI assistant usage: conversations, messages, tokens, estimated cost.

Read the AI generation history for a content variant — the prompt + guardrails snapshot + provider + model + DAM provenance that produced each piece of AI-generated content on this variant. Use to audit off-brand creative ("why does this image feel wrong?") or to trace why a specific variant looks the way it does. Returns { generations, count } with newest first. Each row carries prompt, response, model, tokens, inferred_cost, guardrails (brand_voice + active_briefs + segment), and dam_provider when the asset was push-through'd to a customer DAM.

Get dashboard analytics overview: total sessions, conversions, revenue, segment breakdown, and trend data for the current site. hour_distribution is session COUNTS only — for conversion rate by time of day / day of week, use get_daypart_performance.

Get backtest results showing segment performance, variant impact, conversion rates, and revenue attribution. All figures are windowed (default 90 days) and the window is echoed back in the response. Retired segments are included when they still took sessions in the window, because retiring a segment does not stop traffic scoring into it. This is not the verdict on whether personalization is working — use get_scorecard for that.

Conversion performance by day-of-week × hour-of-day, in the visitor's LOCAL time (first-touch stamps: the hour the visit STARTED; dow 0=Sunday..6=Saturday). THE source for "when do visitors convert / when should campaigns run?" — never infer timing from a time-based segment's lift, which usually comes from the segment's other clauses. Returns: `grid` (dow×hour cells, up to 168 — only combinations with at least one session appear, so never index it positionally; raw sessions and converting_sessions per cell, no per-cell rate on purpose: cells are small, judge significance from the counts before ranking them), `weekday_weekend` and `hour_blocks` rollups (with rates — prefer these for headlines; blocks are a fixed vocabulary, so check the grid for a peak straddling a block boundary), `window` (rates are floored at first conversion, like the dashboard CVR — days/floored say what span the rates actually cover), and `coverage` (measured_sessions the grid describes, vs rate_window_sessions — every session in that same floored window). Numerators are primary-goal converting sessions (the conversions ledger, as in get_analytics conversion_stats), but computed over the measured subset only: sessions without first-touch stamps and simulator sessions are EXCLUDED, never guessed, so rates here legitimately differ from conversion_stats wherever coverage is below 100% or simulator traffic exists — that gap is deliberate exclusion, not a data problem.

Get recent site events: pageviews, clicks, conversions, custom events.

Form conversion funnel analytics: views → starts → submits → abandons, per form and per page, with field-level drop-off.

CONVERSION-RATE lift vs the always-on holdout control group (not revenue — revenue lift lives on get_scorecard). Default: the per-variant table. Pass `offer_id` for the per-OFFER roll-up (#1476): treated-vs-holdout CVR pooled across the offer's placements, delivery volume, and — once discount capture is live — an observed `redemption` block (redemptions, order-level discount spend, holdout-redemption leakage signal) that is explicitly NON-CAUSAL: redemption says people accepted free money, and the holdout comparison is the causal number. The response's `not_measured` array names what the report deliberately does not claim (incremental margin needs observed exposure). Pass offer_id="" (empty string) to get every offer on the site. The response carries `holdout_epoch` — arms are measured per VISITOR only since `epoch_started_at` (#1380 cutover); pre-cutover per-visit sessions are excluded, so a window that spans the cutover covers fewer sessions than its day-count implies.

Get the AI Scorecard — the plain-language verdict on whether personalization is beating the 10% holdout control group. Returns status (winning/flat/losing/learning), site-level lift % with statistical significance (z-test p-value), with-AXO vs holdout conversion rates, and a per-segment breakdown. Falls back to a labeled projected lift when live holdout traffic is too thin. Prefer this over get_lift_report for "is the AI working?" questions. The response carries `holdout_epoch` — the verdict is computed on per-VISITOR sessions only since `epoch_started_at` (#1380 cutover); pre-cutover per-visit sessions are excluded, so a window spanning the cutover covers fewer sessions than its day-count implies.

Performance metrics for a segment: sessions, conversions, rate, revenue, AOV. Also returns `attribution` (30-day window): `label_timing` says how many of the converting sessions ending in this segment already carried the label BEFORE they converted - `post_conversion_label_share` near 0 means the blended conversion_rate is real, while a high share means the segment absorbs converters after the fact (their conversion behavior produced the classifying signals) and the blended rate must never be quoted as intent or opportunity. `entry_label` is the strictest cohort - sessions already in this segment at their first event - and its conversion_rate is the honest predictive number to quote when the share is high. `attribution` is null when the segment has no conversions to attribute or the measurement failed.

Sitemap crawl status, page counts, health metrics.

Tag health: 24h beacon/pageview/personalization counts, render errors, first and last event time (lifetime, not windowed), and status — healthy (beacons in 24h) | no_data (none in 24h but this site HAS reported before, so something stopped) | no_signal (never reported at all; a fresh or unvisited install, not evidence of breakage). Also per-goal liveness (goal_liveness / goals_never_fired_90d): a goal with last_fired_at null has fired ZERO times in 90 days — usually a misconfigured detection rule (wrong URL pattern, tag not on the conversion page), not an absence of conversions.

Performance metrics for a content variant: impressions, conversions, rate, render errors.

Create a new custom behavioral segment with a name, description, and signal rules.

Permanently delete a profile and all associated data (GDPR erasure). Removes identifiers, unlinks sessions, deletes the profile.

Designate a SITE-NATIVE form (one the customer already has — newsletter, contact, signup) for opt-in lead capture, or update its field selectors. On submit of a matching form the tag captures the email (plus name/phone ONLY when their field selectors are set here or via data-axo-*-field attributes) into Leads/profiles/CRM. Works on native Episerver/Optimizely Forms too — their AJAX submit is captured via the same vendor hook that fires form_submit. For split-name forms (First + Last as separate inputs, e.g. Episerver) set first_name_field + last_name_field and the tag joins them into the one stored name; use name_field for a single combined input. Upserts by form_selector (max 20 designated forms). This reads visitor-entered PII from the customer's own form — only designate forms the customer owns and has asked to capture; it is inert in passive mode. Verify the selector matches exactly one <form> on the live page first (e.g. via get_form_funnel form ids or probe_zone_binding).

Answer "why did this visitor see this variant?" - or why they saw nothing - with a trace assembled from records. Returns `trace`, an ordered list of claims each carrying the exact rows it rests on: the cohort the scorer assigned and the signals behind it, the holdout arm and which bucketing epoch it was made under, the zone, every live variant's targeting predicate evaluated through the same evaluator the tag itself uses, allocation, and the personalization_applied event that names what actually rendered. Also returns `answer`, the same trace rendered to text by a pure function - no model writes any part of this response. TRACED, NOT INFERRED: report the verdict and the claims AS WRITTEN, offer the cited records when asked how you know, and never supply a reason the trace does not contain. Claims marked "unknown" are first-class answers with a stated reason, not gaps to fill. The most important one: display-rule outcomes (country and schedule gates) are evaluated in the visitor's browser and deliberately never beaconed or persisted, so nothing server-side can say whether one refused this visitor - say exactly that rather than guessing. A visitor in the holdout saw nothing BY DESIGN, and that is a complete and correct answer, not a fault. Identify the visitor by their durable vt_sid visitor id (sessions.cookie_session_id, returned by get_sessions and get_profile) or by a single session id. Name a zone to ask why nothing served there; omit it to explain the most recent recorded exposure. Read-only: reading a trace never changes what AXO serves.

Export a segment's audience for a batch email campaign. Returns JSON rows by default; set format:"webhook" to POST them to a URL. For an email blast list set email_only:true — only profiles with a captured email are included (anonymous visitors excluded). Works for behavioral AND custom/affinity segments (auto-detected). include_pii is required to emit emails and is recorded for compliance.

Manually run K-Means machine-learning clustering against recent behavioral profile activity.

Get detailed profile information including timeline, identifiers, CRM attributes, lifetime signals, session history, lead status (lead_captured history), and the opportunities this profile is a contact/lead on.

Paginated list of profiles in a segment with their identifiers.

List everything currently acting on one segment - zone variants, triggers, recurring audience syncs and recent exports - each annotated with whether the goals measured downstream of it are the goal the segment's conversion thesis names. Serving is zone-local, so five touchpoints can pull one segment in five directions with nothing above them noticing; this is the view where that disagreement becomes visible. Alignment is MEASURED, never inferred from copy: a variant is credited with the goals hit in sessions that saw it, a trigger with the goals hit by profiles after it fired. Below the observation floors the verdict is "undetermined" with a reason - report those as written rather than treating them as alignment. A segment whose thesis says "insufficient evidence" has no primary goal to align against, and alignment_blocked_by says so instead of every touchpoint being guessed at. Exports are annotated with whether the THESIS travelled with the membership list, not with a goal: AXO does not observe what an audience converts to off-platform. Descriptive only - this view reports what it finds and never re-targets anything. Use it when asked why a segment is underperforming, or before adding another touchpoint to a segment that already has several.

Get one segment's conversion thesis in full: which site goals it most over- or under-reaches versus the site baseline, an operator-readable reading, the evidence behind that reading (member vs site-wide sessions, conversion rates, and per-goal reach measured in the window), the confidence, and whether the thesis is stale. Works for pack, custom, ad-source, and ML-discovered segments. Every figure traces to a measurement in the window; a segment with too little traffic returns an explicit insufficient-evidence reading rather than a guess. Descriptive only - reading a thesis never changes what AXO serves.

List all behavioral segments (plus operator-built custom segments) with session counts, conversion rates, descriptions, and each segment's conversion thesis. Counts are live over the last 30 days, consistent with get_analytics segment_distribution. Use this to understand how visitors are being classified. Segments AXO discovered from behavior also carry `discovery`: what the group keyed on, as plain comparisons against the site average ("about 3x the site average"), plus its size, share of traffic, how many recent refreshes it has appeared in, and a coarse quality grade. Use it to explain why a discovered segment exists. `discovery` is null for rule-based segments (read their signal_rules instead) and for discovered ones the latest run did not produce. Its comparisons are deliberately coarse and its states ("too small to characterize", "no distinguishing signals") are honest — report them as written and do not extrapolate exact figures from them. Where `discovery` says what a group keyed on and the description says WHO is in it, `thesis` says why it matters to conversion: which site goals it over- or under-reaches, a short reading, and how much evidence is behind it. `thesis` is null when none has been built yet, and carries stale:true when the goals or the segment membership changed after it was written. Use get_segment_thesis for the full evidence behind one segment. The thesis is descriptive: it does not change what AXO serves. Every row also carries `expected_alignment`: non-null when the segment's own DEFINITION is upstream of, or overlapping with, a site goal, so its lift on that goal is fixed by construction rather than discovered - a form-starter segment against a form-submit goal, or a cart-adder against a purchase goal - or MEASURED from label-vs-conversion ordering (reason `post_goal_labeling`): a large share of the segment's conversions only received the segment label at or after the conversion itself, meaning visitors are classified by behavior the conversion produces, not behavior that predicts it. Scorer rows also carry `label_timing` (30-day window): of the converting sessions ending in this segment, how many carried the label before converting - `post_conversion_label_share` near 0 means the blended conversion_rate is trustworthy, and null label_timing means the measurement did not run (not that the segment is clean). When `expected_alignment` is set, report the number if asked but never present it as a finding, an opportunity, or evidence that the segment is high-intent, and never lead an audience report with it; its `label` says why in one sentence. null means the ordinary case, where the lift IS a finding.

Get recent visitor sessions with behavioral signals, segment assignment, and page URLs. Useful for understanding real-time visitor behavior.

Link a new identifier (email, phone, external_id) to a profile.

Find profiles sharing identifiers (merge candidates for deduplication).

List captured leads (lead_captured events) for this site: contact info, scheduled appointment slot, behavioral segment, and source page.

List the SITE-NATIVE forms designated for opt-in lead capture. Designated forms are the only native forms the tag ever reads values from — on submit, the email (and name/phone when field selectors are designated) lands in Leads, profiles, and CRM auto-intake. Forms can also be designated config-free by adding the data-axo-optin attribute in the site's own HTML; those do NOT appear here. Use get_form_funnel to discover which native forms exist and how they perform before designating one.

Merge two profiles. Moves identifiers, sessions, conversions from source to target, deletes source.

Mint single-use link tokens so an email sent from a third-party ESP (Klaviyo, HubSpot, Mailchimp, Braze, Salesforce Marketing Cloud) can identify the recipient on click. Give it the column the ESP list is keyed on — usually email — and it returns a merge-field column: paste axo_token (or axo_link, if you pass landing_url) into the send, and when a recipient clicks, the AXO tag on the landing page redeems it and the anonymous session merges with their known profile. Recipients with no matching profile come back under unresolved_recipients and simply get no token; their send still works, the visitor just stays anonymous. IMPORTANT: this is deterministic identity, not authentication — a forwarded email hands it to whoever opens it, so use it to personalize content, never to unlock account data, order history or PII. Tokens are single-use and expire (72h default); re-mint per send rather than reusing a column. Profiles that declined marketing consent are skipped automatically.

Remove a native form's opt-in capture designation by its form_selector (see list_optin_forms). The tag stops reading that form on the next config refresh; already-captured leads are unaffected.

Search visitor profiles by email, segment, or identification status. Returns profile list with identifiers and session counts.

Remove an identifier from a profile.

Update a profile segment override or lifetime signals.

Update a segment: rename, edit description, change emoji, visibility, or signal rules.

Attach a library asset to a content variant field — overwrites whatever image was on that field with the asset's blob_url. Also copies the asset's provenance (prompt, brief / reference / planner attribution, tags) into the variant's generated_metadata so the audit trail follows the image. Returns { ok, asset_id, variant_id, blob_url, field_key }. Use after search_assets surfaces an existing asset that matches what the operator wants — saves a generation call. The variant's image_url is also synced to the asset's blob_url so the runtime tag picks it up immediately.

Author a "move object" placement: relocate an EXISTING element on the page to a new location, WITHOUT changing its copy or injecting new content (pure rearrangement). Creates a source zone (element_selector = the element to move) + a move_object content variant whose payload carries the destination anchor + position. Use after a two-pick (the extension / preview picker gives you source_selector + dest_selector). Target ONE segment via segment_id, OR all_visitors:true for everyone (the default — moves are usually global). CAUTION: once published this ships to the live site within ~60s. To preview without persisting on a no-tag site, use the extension demo flow instead.

Clone a system or site template into a new site-owned template.

Configure a product_reco variant: choose recommendation mode (auto / curated / mixed), retrieval strategy, catalog filters, catalog weights, and pinned products. A FILTER removes items ("do not recommend anything with 10 or fewer in stock"); a WEIGHT re-ranks them without hiding them ("de-emphasise low stock"). Reach for a weight whenever the ask is to show something less rather than not at all. Call list_catalog_filter_fields first so field names are real. Use list_products to find product IDs.

Create a new campaign with a brief (objective, offer, tone, themes).

Create a personalized content variant for a zone + segment combination. For copy_swap/hero_swap, check the zone's field_schema (get_zones) FIRST and key the payload by its payload_key/canonical_name entries — a payload sharing NO renderable key with a schema-bearing zone binds nothing and is refused with a 400 naming the accepted keys. Do not copy another variant's payload shape without checking the target zone's schema. For product_reco variants, create with an empty payload ({}) and then call configure_product_reco to set the recommendation mode and curated products.

Create a reusable lead-capture form template. The payload is the form design; it is copied onto each placement.

Create an offer in this site's library. It is ALWAYS created as an UNAPPROVED DRAFT: a human must ratify it in the dashboard (approve the terms, and attest the code exists and is active in their commerce platform) before it can ever serve. There is no `status` argument here and no tool on any surface that can make an offer live — that transition is dashboard-only, by construction. MONEY IS CENTS AND PERCENTS ARE BASIS POINTS, integers only: value_bp 2500 = 25% off, value_cents 1000 = $10 off. The write is REJECTED when the depth exceeds the site's max_discount_pct ceiling, or when it meets/exceeds the site's gross margin (every order at that depth loses money and no conversion lift can fix it). `code` must be a discount code the merchant's platform ALREADY honors — fulfillment_mode accepts only "existing_code". Returns { id, warnings }; warnings cover mirrored terms and the break-even lift this discount needs. Then place it with place_offer.

Create a page type configuration for sitemap analysis.

Create a new triggered message. Requires name, mode (immediate|dormancy), watch_event, and at least one destination.

Create a new site-owned payload template for triggered messages.

Create a new personalization zone on the site. For lightbox zones (zone_key="lightbox"), pass display_rules to set when/where/who/how-often the popup fires — including country targeting (audience.country) and day/hour windows (schedule); otherwise call list_lightbox_presets and use one of those rule objects verbatim.

Delete a campaign permanently.

Soft-delete a content variant. The variant is hidden immediately but recoverable via restore_content_variant within 30 days. A history snapshot is automatically created before deletion.

Delete a form template. Already-deployed placements are unaffected (placements copy the payload).

Soft-delete an offer. It vanishes from list_offers and stops being hydrated on the next config build, but the row survives so historical per-offer lift stays attributable. Its PLACEMENTS are deliberately not deleted: they keep their offer_id, hydrate to nothing, and are dropped from tag config, so the page shows no half-resolved offer rather than a stale code — fail closed. If a slot should now carry something else, remove or repoint the placement yourself with delete_content_variant.

Delete a page type configuration.

Permanently delete a trigger and its fire history.

Delete a site-owned trigger payload template.

Delete a zone and all its content variants.

Use AI to generate a content variant draft for a segment + zone. Returns suggested headline, body, and CTA.

Get the multi-armed bandit optimizer status. Shows Thompson Sampling allocation weights, which variants are winning, conversion rates per variant, and Beta distribution parameters.

Get full trigger configuration: events, dormancy, identifier type, destinations, payload templates.

Get full details of a trigger payload template.

Get personalization zones. Pass zone_id to fetch a single zone (recommended when working on a specific zone — full response is 200KB+). Without zone_id, returns all zones for the site.

List all campaigns for the site with status and briefs.

List reusable lead-capture form templates for this site. Each has a name and a payload (title, cta_text, tcpa_text, success_text, accent_color, fields[], calendar_enabled).

List the canned lightbox display-rule presets (Welcome offer, Exit intent newsletter, Cart recovery, Promo bar, Returning visitor offer). Each preset returns a complete DisplayRules object that can be passed verbatim as create_zone.display_rules or update_zone.display_rules. Use this instead of authoring the rules JSON from scratch unless you need a custom combination.

List this site's offer library plus the guardrail dials every offer write is validated against. Returns each non-deleted offer (name, status, offer_type, value_bp / value_cents, code, validity window, stacking, approved, code_verified_at), `site_dials` (max_discount_pct — the hard depth ceiling; gross_margin_pct — null when the operator has not configured one), and a per-offer `break_even` hint: the relative conversion lift the discount must produce just to pay for itself (d / (m - d)), null when no margin rate is set. Call this before authoring or placing anything — it is how you tell a ratified, servable offer (status "live" AND approved AND code_verified_at) from a draft that will render nothing. AXO is a SHADOW promo layer: these rows REFERENCE a discount code the merchant's own platform already honors; we never mint one and never touch redemption accounting.

List page type configurations (product, category, blog).

Get the audit log of fire attempts for a trigger: successes, errors, skipped fires with skip_reason.

List available payload templates: system seeds and site-owned custom templates.

List all triggered messages for the site with watch event, mode, destinations, and enabled status.

Deploy a lead-capture form onto a page: creates a lead_form content variant bound to a zone (anchor) + audience. The form INSERTS relative to the anchor by `position` (default "after" — slots between sections without taking over). Target ONE segment via `segment_id`, OR set `all_visitors: true` to show the form to EVERYONE regardless of segment (provide exactly one). Get a payload from list_forms (copy-on-place) or pass one directly. To anchor somewhere that is not yet a zone, call extension_pick_element then create_zone first.

Deploy an offer into a zone: creates a type="offer" content variant bound to a zone + audience. Target ONE segment via `segment_id`, OR set `all_visitors: true` to show it to EVERYONE regardless of segment (provide exactly one). The placement stores ONLY the offer_id plus presentation overrides — the economics (value, code, window, terms) are joined in from the offer row on every config build, which is what makes an offer ending at midnight go dark everywhere instead of leaving a stale code on the page. The renderer writes into the anchor zone's element, so pick a zone whose contents the offer should own (create_zone first if none exists). Two DIFFERENT offers cannot compete in one zone + audience and the write is rejected if you try: the optimizer ranks on conversion rate, so given a choice of depths it always crowns the deepest one and reports the lost margin as a win — competing arms must share one offer and vary only presentation. Placing an unapproved or non-live offer succeeds but serves nothing until a human ratifies it in the dashboard; check status/approved via list_offers first.

Restore a content variant. Two modes: (1) pass only variant_id to un-delete a soft-deleted variant; (2) also pass version to roll back the payload to a specific historical version (use get_content_history to find version numbers). Restoring to a version is itself snapshotted, so you can always roll forward again.

Return the segment-aware donation ask ladder for a donor — the amounts a fundraising form should show first, plus the recurrence default + rationale. Pass `segment_suffix` for the default ladder per segment (e.g. "donor_ready", "high_capacity_uncontacted", "lapsed_quarterly"), OR pass `profile_id` to personalise off the donor's CRM-fed attributes (last_gift_amount_cents / recurring_amount_cents / lifetime_giving_cents / capacity_score). When `profile_id` is given without `segment_suffix`, the profile's current segment is used. Returns { ladder: { amounts_cents, recurrence, rationale, highlight_index?, highlight_label? }, resolved }. Amounts are in CENTS. Use before authoring a copy_swap variant that writes the amounts onto a donation form, or when the agent needs to suggest "what should we ask for" from the donor context.

Fire a trigger against a test target, bypassing cooldown/rate limits. Goes through the real dispatch pipeline — WILL send real email/SMS.

Update a campaign name, brief, or status.

Update a content variant payload or active status. A history snapshot of the previous state is automatically saved before the update, so changes are always reversible via restore_content_variant. When replacing a copy_swap/hero_swap payload, read-modify-write against the zone's field_schema keys — a re-keyed payload sharing NO renderable key with the zone is refused with a 400 naming the accepted keys.

Update a form template name and/or payload.

Update an offer's terms, or move it between draft / paused / archived. `status` accepts ONLY those three. "live" is a dashboard-only transition gated on human approval plus code verification, and it is refused outright on the API-key path that every agent surface authenticates with — so you CAN pause or archive an offer that is misbehaving, and you CANNOT start one. Ask the operator to approve it in the dashboard instead. Editing the economics (offer_type, value_bp, value_cents, currency, tiers, gift_sku, code) UN-RATIFIES the offer and it stops serving until a human re-approves: approval attaches to specific terms, not to a row id, so a 10%-off offer approved yesterday can never silently become 40% off today — the response reports `approval_reset`. Changing `code` also clears the code verification. Same units and guardrails as create_offer (cents, basis points, the site depth ceiling, the margin floor). OMITTING a field leaves it untouched; sending it as NULL REMOVES it, which is how you make a promo open-ended (ends_at: null = runs indefinitely) or drop a threshold, a cap or a link. Only starts_at, ends_at, min_order_cents, max_discount_cents, max_exposures_per_visitor, code, redeem_url and terms_url accept null — null on anything else is rejected rather than ignored, so a mistaken null never silently no-ops. The response echoes what you removed as `cleared`.

Update a page type configuration.

Update an existing trigger. Pass only the fields to change.

Update a site-owned trigger payload template.

Update an existing zone (selector, name, priority, approval, display_rules, or field schema). To add a missing field (e.g. image_url): call get_zones(zone_id) first to read the existing field_schema, then pass the full updated array with the new entry appended.

Approve the current revision (preview → approved). Precondition for publish_page; still not public.

Accept a page suggestion: creates an UNPUBLISHED draft page from the proposed brief. Pass amendments to extend the brief. Generate and publish are separate steps.

Create a draft page from an operator-stated goal (no suggestion needed). target is the question the page must answer. Returns the draft; call generate_page next.

Route the right visitor to a published axo Page: creates an entry-point variant (copy_swap/hero_swap) whose CTA the server points at the page (<pageUrl>?vt_route=<variantId> — the attribution join key; never supply URL fields yourself). Rides the full variant machinery: campaign flight window + audience AND-composition via campaign_id, eligibility/segment targeting, priority, per-visitor holdout, lift. Called WITHOUT zone_id it returns needs_zone with candidate zones — pick the one whose page_pattern covers where the audience lands (only zones whose schema carries a url field can host a route). An approved-but-unpublished destination is allowed only with active=false (the suggestion-loop shape); publishing the page re-stamps the href.

Dismiss a page suggestion. The underlying gap stays quiet for the cool-off window.

Render a revision of a page from its brief. SLOW: takes 60-120s or more — wait for it. With feedback, regenerates applying it — feedback accumulates, so every regeneration honors all prior feedback. Returns the preview URL. Costs AI budget. A 409 generation_in_flight means a render is already running: do NOT retry — poll get_page for a new revision; if none appears within 6 minutes the lease has expired and one retry is safe.

Get content variants. Pass zone_id to fetch only variants for a single zone (recommended — the full response is 1MB+). Without zone_id, returns all variants for the site.

Get the version history for a content variant. Returns up to 20 snapshots ordered newest first, each with version number, who changed it (api or dashboard), when, and the full payload. Use this before calling restore to find the version you want.

One page in full: brief, revision history, publications, shareable preview URL (pre-publish, noindex) and the public URL when published.

The OBSERVED route funnel per route (shown → routed_sessions via vt_route → destination conversions), descriptive not causal — filter by variant_id or campaign_id (the campaign rollup), days 1-90 (default 30). For the CAUSAL number use get_variant_performance: a route is an ordinary variant to the holdout lift lane.

Import a design into axo from a publicly fetchable URL. The file is a self-contained HTML bundle with all images, fonts, and styles inlined.

List captured content-backlog sources for the blog pipeline. Filter by status (new/used/skipped) and recency.

List suggested pages for this site — each an answer-engine visibility gap (a question no engine answers with this brand) with evidence and a proposed archetype + outline. Accepting creates an unpublished draft; nothing publishes itself.

List generated pages for this site with status (draft, preview, approved, published, retired).

Every route on the site: entry variant, hosting zone, audience, campaign (name/status), destination page, and health — destination_published=false flags a route whose page will 404.

Log an interesting article, link, or point of view into the content backlog. The weekly blog pipeline drafts posts from these. Provide a url and/or a note explaining why it matters.

PUBLISH a page — the one action that makes it public and indexable, at /p/<site>/<slug> (axo_hosted), or at https://<custom-domain>/<slug> (custom_subdomain, needs a live page domain).

Rename/move an UNPUBLISHED page (draft, preview, or approved) to a new slug/path — the recovery for a typo'd folder. May be a nested path like "blog/spring/launch" (max 5 segments). Refused once the page is published or retired: the slug is write-once after publish. 409 slug_taken means another page holds that path — pick a different one. Preview links survive a rename.

Retire a page: unpublishes any live publication and ends its lifecycle. History is kept.

Get the status and list of imported products in the catalog.

The content-site counterpart of list_products: what the crawl understands about a site, grouped section (first URL path segment) → page type, with 30-day engagement per section. Pass `section` to list that section's pages (title, URL, page type, AI summary, meta description, h1, categories, personalization hooks, curation state). Works for any archetype; most useful on non-ecommerce (B2B, lead-gen, content) sites.

Retrieve the parsed taxonomy mapping representing the site hierarchy.

Import products into the product catalog. `url` must point at the product-detail page — it is the natural key, and rows without one are skipped. `inventory_quantity` is the only real stock number the system holds and is what makes rules like "don't recommend items with 10 or fewer in stock" expressible (see configure_product_reco filters).

What can recommendations be filtered or weighted on? Returns every product_catalog column an operator may write a predicate against, READ FROM THE LIVE SCHEMA (so a column added by a recent migration is listed the day it exists), plus the operator list, the weight multiplier range, and the missing-value rules for filters and weights (which differ). Call this before configure_product_reco filters or catalog_weights so field names, ops and multipliers are real rather than guessed.

Search and list catalog products/items for a site. Allows filtering by category, specific product IDs, or including ignored items.

Ready-made recommendation rules — exclude out of stock, de-emphasise low stock, exclude discontinued, rating floor, require a product image, and so on. This is the answer to "what can I filter on" for someone who does not already know: a list rather than a schema. Each preset returns the LITERAL filters and catalog_weights it would write, plus an impact preview measured against this site's own catalog — how many items it would drop, how many it would re-rank, and which referenced columns have no data at all (a rule on an unpopulated column changes nothing, which is worth saying before it is applied rather than after). Apply one by passing its filters / catalog_weights verbatim to configure_product_reco; there is no one-word apply on purpose. State the rules and the impact to the operator before applying them. A preset naming a column this catalog does not have comes back with available:false and the reason.

List the site's taxonomy terms — the brand/topic/category vocabulary that drives per-visitor interest/affinity scoring. Optionally filter by dimension.

Merge and rename product categories (renames a category across all products in sitemap and page profiles).

Change a catalog product/item details (category, name, brand, description, sku, price) or mark it as ignored (which hides it from the personalization catalog and excludes it from variant recommendation). Sets is_override to true.

Curate one content-map page (the page_profiles counterpart of reclassify_catalog_item): override its page type or section (null restores the crawl/derived value), or set ignored to hide it from the content map and reco candidates.

Rename a content-map section across the site's pages (writes a curation override; re-crawls never undo it). Merging two sections is the same operation: rename A to B and A's pages join B's bucket.

Extract brand colors directly from the live homepage (meta theme-color, CSS custom properties, button styles). Pass persist:true to save the detected colors into the site's brand settings — fills only colors that are currently unset, never overwrites operator-chosen values.

Generate a NEW image via the site's BYOK image provider (gemini | openai | firefly). Real, paid API call (~$0.04) — call search_assets FIRST and reuse an existing asset when one matches. provider + prompt required. Optional: model, width, height, negative_prompt; use_brief prepends brand-voice + active-campaign context; zone_key / variant_type add visual context; reference_images (catalog product / URL / data URL) and plan_with_claude require experimental_creative_enabled. When experimental_generative_dam_enabled is on, the image is persisted and the result carries asset_id + blob_url — pass that asset_id to attach_asset_to_variant to place it on a variant. The base64 data_url is OMITTED from the result (too large); fetch blob_url for the bytes.

Fetch one DAM asset by id — includes the full generation_metadata (user_prompt, enriched_prompt, brief / reference / planner attribution) and tags. Use to inspect an image's provenance before re-using or attaching it. search_assets returns the list view (no generation_metadata); this is the detail view.

Import and configure site brand definitions from a Figma file URL.

List the customer's DAM connections (Cloudinary, S3-compatible, etc.) for this site — masked credentials, active flag, provider metadata. Use before search_dam to discover which DAMs are wired (or to confirm one is connected before suggesting search_dam to the operator). Returns { connections: [{ id, provider, provider_meta, config_preview, active, ... }] }; credentials in config_preview are masked (api_secret as "••••XXXX"). Empty array when no DAM is connected.

List BYOK image-gen provider credentials for this site (Gemini, OpenAI, Adobe Firefly). The generate_image tool routes through whichever has saved credentials + provider matches the request. Use to discover which providers are available before suggesting generate_image, or to confirm a custom_model_id (BYOM) is set on a connection. Returns { keys: [...] } with masked credentials.

List BYOM text-gen credentials for this site (OpenAI-compatible endpoints — vLLM, Ollama, Azure OpenAI, LM Studio). When a key is active AND experimental_byom_enabled is on, /api/content/draft routes the variant-authoring AI calls through it instead of platform Anthropic. Use to discover whether the operator has BYOM text wired before suggesting draft_content_variant. Returns { keys: [...] } with masked api_key fields.

Create an AXO thin asset record from a brand-DAM asset (e.g. one returned by search_dam). Returns { id, url, reused } — the id is the asset_<uuid> you pass to attach_asset_to_variant. Dedups by (site_id, dam_provider, dam_asset_id) so picking the same asset twice reuses the existing row. No bytes pass through AXO; the asset stays in the customer's DAM. Gated on experimental_byo_dam_enabled + an active connection for the named provider.

Search the generative DAM asset library for previously-generated images. Filters: q (text match on name + prompt, ILIKE), subject (tags.subject exact), theme (tags.themes contains), provider (gemini|openai|firefly), include_archived (default false). Returns up to `limit` assets with their blob_url, name, prompt, provider/model, and auto-tagged subject/scene/themes/palette. Use this BEFORE generating new images — if the operator asks for "a warm autumn kitchen background" and one already exists in the library, attaching it saves $0.04 of generation cost and ~3 seconds of wall-clock. Requires experimental_generative_dam_enabled on site_config.product_catalog.

Search the customer's CONNECTED brand DAM (Cloudinary, S3-compatible) for assets — including ones the brand team uploaded directly without going through AXO. Use when the brand owns assets you want to BIND to a variant rather than generate fresh: the brand has approved imagery you should reuse. q matches filename + public_id + tag values (Cloudinary) or key-substring (S3); folder scopes to a folder prefix; tags filters to assets carrying ALL of the listed tags (Cloudinary only — S3 tags aren't indexed for search). Returns hits with asset_id (vendor public_id / S3 key), external_url, mime_type, tags, folder. THREE-STEP BIND FLOW: search_dam → register_dam_asset (creates AXO thin record + returns asset_id) → attach_asset_to_variant (binds to a variant field with provenance). Returns empty when no DAM is connected — search_assets handles the AXO-side library separately.

Update a DAM asset: rename (name), replace its tags (tags object), or archive/unarchive (archived). Pass archived:true to soft-delete — it disappears from search_assets but any variant already pointing at its blob_url keeps working; archived:false restores it. At least one of name | tags | archived must be set. The blob bytes are never mutated.

Create a new integration (klaviyo, braze, resend, webhook, meta_capi, google_capi, google_ads_ec, …).

Delete an integration permanently.

Get full config for a single integration.

Recent fire log for an integration with success/error stats.

List all integrations (Klaviyo, Braze, Resend, webhooks, CAPI) with status.

Push CRM records to enrich visitor profiles. Matches by email, phone, or external_id. Attributes (ltv, plan, customer_tier, etc.) are merged into the matched profile.

Send a test payload to an integration to verify the connection works.

Update integration config, events, or active status.

Start custom-domain onboarding for generated pages: the customer's subdomain (e.g. learn.brand.com) will serve published pages on THEIR domain. Returns DNS instructions: first an ownership TXT record, then a CNAME. Subdomains only (no apex). One domain per site.

Analyze a semantic sitemap structure to optimize category mapping internally.

Switch the current site to a vertical pack: seeds any missing segments/zones/variants and RETIRES the previous composition's pack segments (visible=false — out of the tag's scoring rules and dashboard lists; reversible, history kept, re-applying the old pack restores them). Existing customizations and archetype extensions are preserved unless archetype_extensions is passed explicitly (omit to keep, [] to clear). To ADD a pack alongside the current one instead of switching, include it in archetype_extensions rather than changing vertical. Re-applying the site's current vertical is a safe no-op refresh.

Create or update taxonomy terms (brand/topic/category) with the keyword + URL-pattern rules that map pages to that object. These feed per-visitor affinity scoring and the "Interest / affinity" segment leaf. object_key defaults to a slug of the label. Example term: { dimension:"brand", label:"Titleist", keywords:["titleist"], url_patterns:["/titleist"] }.

PROPOSE (never apply) site-specific query params for extra_tracking_params, from the site's own recent pageviews. Returns proposals with the evidence behind each — occurrences, share of the sample, distinct-value churn, whether any value ever reached a second session, path spread, redacted sample values — plus every observed param it did NOT propose and the rule that stopped it. Two bases: `known_vendor` (a named product's per-click/session token such as Awin's awc or PHPSESSID, proposed on sight) and `traffic_evidence` (cleared every floor on this site's own traffic). A site with too little traffic reports status "insufficient_evidence" and makes NO evidence-based proposal rather than guessing on thin data. This tool CANNOT change page identity: to apply, call update_site_config with the FULL extra_tracking_params list (existing entries plus the accepted ones). CAUTION before applying: declaring a param that genuinely distinguishes pages merges those pages into one page identity, silently and unrecoverably. The detector deliberately under-proposes, so a param it held back was held back on purpose.

Discover and map semantic URLs from the site, identifying structure automatically.

The site's custom page-domain status (awaiting_ownership → awaiting_dns → cert_pending → live) with the exact DNS records to add. Calling this re-checks DNS/SSL state, so it doubles as "check again".

Get current site configuration: brand, mode, conversion goal, settings.

Get the full contents of a vertical pack (segments, zones, variants) before applying it.

List answer-engine visibility findings for this site: blocked AI crawlers, missing structured data, prompts no engine answers with your brand, third-party sources the engines keep citing instead. Ranked worst-first.

List available industry vertical packs (ecommerce, home_services, saas, financial, healthcare, nonprofit, affiliate, content_media). Each pack bundles default segments, zones, and variants tailored to that industry.

Remove the custom page domain: detaches it from serving (pages published to it stop resolving). The hostname stays reserved so it cannot be hijacked while the CNAME lingers.

Move a finding: acknowledge it, mark it resolved, mark it won't fix, or reopen it. Won't-fix is sticky - a re-observation will never reopen it, only an explicit reopen will.

Start a read-only audit of this site's own public surface - robots.txt, llms.txt, sitemap and a sample of pages - and derive findings from it. Costs nothing: no answer engines are queried.

Update site settings: identity (name/domain), brand, mode, conversion goal(s), zone overlap mode, holdouts, passive_mode, anti-flicker dials, activation-orchestrator rollout. Only the fields you pass are touched. `network_contribution` is an OPT-IN to the cross-site observation graph (the site-blind, PII-free IP→company lane — never fed by profiles/emails/form fills), DEFAULT OFF: pass `true` only with the customer's actual agreement, and `false` to withdraw, which also scrubs already-annotated sessions. Pass `goals` (array) to FULL-REPLACE the typed multi-goal list — primary + optional supporting goals; read the current list via get_site_config first since omitted goals are deleted. `conversion_goal` (single URL string) is the legacy single-goal field; passing it materializes a primary URL-kind goal. Pass one OR the other, not both. `passive_mode: true` locks out first-party PII (no lead forms, no identify/CRM writes) while keeping anonymous behavioral + goal/conversion tracking — use for no-PII pilots. Anti-flicker dials: check get_flicker_health first and rule out binding failures (a wrong selector produces the same visible-swap signature); every dial write echoes the holdout-wait tradeoff in the response. `business_brief` records what the operator told you about their business and grounds every AI copy draft — note its facts/beliefs split, which is load-bearing.

Get CRM sync history and enrichment statistics. Shows how many profiles have CRM attributes, total enrichment coverage, and recent sync logs.

Get Salesforce integration status, sync history, and coverage stats. Shows connection state, recent syncs, and how many profiles are enriched from Salesforce.

Which target accounts VISITED the site: cross-references saved company lists (TALs) against sessions whose visitor IP resolved to a company, returning per-account session counts and last-seen. Defaults to every list over the last 30 days; pass list_id and/or days to narrow. A match means an outbound target is now inbound — surface it, and ratify it into the pipeline with pipeline_create_opportunity.

Import a target-account list (TAL) from an external prospecting tool — e.g. an Apollo accounts export — as a saved company list. Provide domains[] and/or paste raw export text as csv: anything domain-shaped is extracted (website URLs, bare domains, the company domain of corporate emails), free-mail domains are dropped, and everything is deduped. Requires the Company Graph module. After importing, use get_target_account_matches to see which target accounts are visiting the site.

Add a contact (name, email, phone, role) to a CRM opportunity. Set is_primary to make them the headline contact.

Append a note to a CRM opportunity's activity timeline (append-only): call summaries, next steps, observations.

Add a task (next step) to a CRM opportunity: "send the quote", "follow up Friday". Every open deal should have a next step — the earliest-due open task shows as the deal's next step on the board and in the digest. due_date is day-granular.

Create a CRM opportunity. Stage must be a key from pipeline_get_funnel (omit for the first open stage). value_cents is the deal value in cents. custom carries values for the account's defined custom fields (see settings.fields).

The account's CRM pipeline definition: ordered stages (key, label, open/won/lost kind, close probability, stale_after_days) plus module settings (auto_create_from_leads, lost_reasons, fields, digest, …) and a vertical preset (suggested stages/lost reasons/fields for the account's business type — a seed to offer, never auto-applied). Call this FIRST before creating or moving opportunities — stage keys are per-account vocabulary, not a fixed set.

One CRM opportunity in full: fields, firmographic enrichment, contacts, tasks, and the activity timeline. Contacts and the company carry live on-site behavioral context — segments, interests/affinities (brand/topic/category), high-intent page signals, sessions, conversions, recency, and hotness — plus a rollup of other open deals at the same company domain. opportunity.lead_quality carries the suspected-spam verdict ({verdict, score, reasons}) or null for never scored; null is an absence of information, not a clean bill of health.

Deals in the CRM trash: soft-deleted, still restorable, newest first — with who deleted each one and the date its restore window closes. Deleted deals are invisible to every other pipeline tool, so this is the only way to see them. Use it when someone says a deal has gone missing, and before telling anyone a deal does not exist. Read-only.

List the account's CRM opportunities (max 500, newest first) with stage, value, primary contact, hot-lead flag — plus the funnel stages for grouping into a board view. Each deal carries lead_quality: {verdict: ok|suspect|spam, score, reasons} when its originating website lead was scored, or null when it was NEVER SCORED (manual entry, agent-created, CSV import). null does NOT mean clean — never describe an unscored deal as verified or spam-free. A suspect/spam deal is excluded from the hot-lead flag; treat it as unqualified until a human releases it from the review queue.

Shadow opportunities ("Companies on your site"): corporate-email domain clusters of identified visitors whose behavior crossed the intent threshold, with evidence (people, sessions this week, top pages). These are deal CANDIDATES AXO observed — not yet in the pipeline. To ratify one, show it to the user and create an opportunity with pipeline_create_opportunity (company from the domain, contacts from the people, source "axo_prospect"). Domains already on open/won deals and dismissed domains are excluded.

List CRM tasks (next steps) across the account's opportunities, earliest-due first. Default: open tasks only. Use due_before with today's date to find overdue tasks, or opportunity_id to see one deal's list. An open deal with no open task has "no next step" — worth flagging to the user.

Log a touchpoint (email, call, or meeting) on a CRM opportunity's timeline. Use external_ref (e.g. "gmail:<message-id>", "gcal:<event-id>") for idempotency — re-logging the same ref returns the existing row instead of duplicating, so sweep agents can re-run safely. For plain observations use pipeline_add_note; for inferred stage moves use pipeline_suggest_stage_move.

Turn a plain-language description of how the business sells into a validated pipeline proposal: stages with probabilities, settings, and a rationale. READ-ONLY — returns the proposal plus the current stages for diffing; nothing is saved. Apply with pipeline_set_funnel after the user approves. Uses an AI call (allowance-metered).

Bring a deleted CRM opportunity back, with its contacts, tasks and full timeline. Ids come from pipeline_list_deleted_opportunities. If the deal's original stage no longer exists in the funnel it lands in the first open stage instead and the response says so in rehomed_to — say that out loud rather than leaving the user to find the card somewhere unexpected. Fails once the restore window has closed, at which point the deal is genuinely gone.

Save the account's CRM pipeline: stages replace wholesale, settings merge per key (a single knob never wipes the others). Stage validation: 3-12 stages, snake_case keys, exactly one won + one lost stage, probabilities 0-100, optional stale_after_days (1-365, open stages) for the stale-deal nudge; a stage currently holding opportunities cannot be removed (move them first). Omit stages to change settings alone.

Propose (not perform) a stage move on a CRM opportunity: appends a suggestion the user accepts or dismisses in the CRM. USE THIS whenever you INFER a deal progressed — pipeline_update_opportunity is only for user-directed moves.

Update a CRM opportunity — move stage (auto-logs a stage_change and fires the behavioral rail), change value, title, close date, custom fields, or record a lost_reason. Only pass changed fields. IMPORTANT: only move stages when the user asked for the move or approved a suggestion; when you merely INFER progress, use pipeline_suggest_stage_move instead. When moving a deal to the lost stage, ask for (or infer from the user's words) a short lost_reason.

Update a CRM task: complete it (status done), skip it, reopen it, reschedule (due_date), or edit the title/body. Completing or skipping logs a system activity on the deal's timeline.

Trigger a Salesforce sync. Direction can be outbound (push AXO→SF), inbound (pull SF→AXO), or bidirectional.