Update a site

Replaces the site's `name`, `platform`, and `url` together, and optionally patches its AI-assistant-context fields (`siteInformation`, `toneOfVoice`, `vertical`). This does not accept a partial `name`/`platform`/`url` update: always send all three, unless the body carries only settings (the automation settings `autoGenerateStarters`, `switchOnGeneratedStarters`, `pageViewCountingEnabled`, `storefrontCartCountingEnabled`, `autoReadPages`, `autoReadMinViews`, `tagMonitoringEnabled`, the panel colours `panelColors`, the panel side and opening mode `panelPosition` and `panelBackdrop`, and the Panel reduced state button's `resumeButton`), which change those settings and nothing else. Each changed setting records its own audit entry (`autoReadPages` and `autoReadMinViews` share one, so do `panelPosition` and `panelBackdrop`, and `resumeButton` records one only when a value changed), and a body that mixes settings with other fields also records the site update. The whole body is validated before anything is written, so an invalid threshold, colour or offset changes nothing.

Authorization

ApiKeyAuth

AuthorizationBearer <token>

A WorkOS org-scoped API key, created from the dashboard's organization settings page. Identifies the tenant every read and write is scoped to. Missing, malformed, unknown, revoked, expired, or non-organization-owned keys all return 401 (no distinction, so the response can't be used to probe which keys or org ids exist).

In: header

Path Parameters

siteId*string

The site id (prefixed site_). A site id that isn't yours is a 404, same as any other cross-tenant id.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Send name, platform and url together, with the optional fields you want to change, or send only autoGenerateStarters or switchOnGeneratedStarters.

resumeButton?

Changes the Panel reduced state button's settings, the same keys as resumeButton on the site. Patch-style: a key sets its value, null returns it to its default, an absent key stays unchanged; colors patches each colour the same way. The icon colour cannot be none. It applies on the next page load and records a branding audit entry when something changed. Send it alone to change nothing else.

name?string

Display name (1–200 characters). Sent on every update: this endpoint replaces name/platform/url together, it does not patch a single field.

Length1 <= length <= 200

platform?SitePlatform

The platform the site runs on. Most values are e-commerce platforms (shopify, prestashop, woocommerce, commercetools, bigcommerce, adobe_commerce, salesforce_commerce, sap_commerce, wix); hubspot, wordpress, and wix_site are non-commerce website builders/CMSs (a marketing site rather than a storefront).

Value in

"shopify"
"prestashop"
"woocommerce"
"commercetools"
"bigcommerce"
"adobe_commerce"
"salesforce_commerce"
"sap_commerce"
"wix"
"hubspot"
"wordpress"
"wix_site"
"custom"

url?string

The storefront's public address, same rules as on create.

Length1 <= length

siteInformation?string

Free text describing what the site sells, for grounding the assistant's context. Optional and patch-style: omit to leave unchanged, send null or an empty string to clear it.

Lengthlength <= 3000

toneOfVoice?string

Free text describing the brand's tone of voice, for grounding the assistant's context. Optional and patch-style: omit to leave unchanged, send null or an empty string to clear it.

Lengthlength <= 800

vertical?string

The site's business vertical, used to give every agent on this site vertical-specific guidance. Optional and patch-style: omit to leave unchanged, send null to unset.

Value in

"retail"
"health_beauty"
"electronics"
"food_beverage"
"home_garden"
"fashion_apparel"
"travel_hospitality"
"other"

autoGenerateStarters?boolean

Turns automatic starter-question generation on or off. It applies at once and records its own audit entry. Send it alone to change nothing else.

switchOnGeneratedStarters?boolean

Turns on or off writing generated starter questions switched on. When on, questions reach shoppers as soon as they are written, with no review. It applies at once and records its own audit entry. Send it alone to change nothing else.

pageViewCountingEnabled?boolean

Turns page-view counting on or off for the site. It applies at once and records its own audit entry. Send it alone to change nothing else.

storefrontCartCountingEnabled?boolean

Turns on or off the recording of the add-to-carts and orders the Shopify pixel reports from the site's own pages. It applies at once and records its own audit entry. Send it alone to change nothing else.

autoReadPages?boolean

Turns the automatic reading of discovered pages on or off. It applies from the next daily run and records the automatic reading audit entry. Send it alone to change nothing else.

autoReadMinViews?integer

The views over 30 days a discovered page needs to be read automatically: a whole number from 0 to 1,000,000. Any other value is refused with 400 and nothing is changed. Changed with autoReadPages or alone, it records one automatic reading audit entry carrying both values.

Range0 <= value <= 1000000

tagMonitoringEnabled?boolean

Turns the hourly check of the tag on the site's homepage on or off. Turning it off also closes the site's open alert. It applies at once and records its own audit entry. Send it alone to change nothing else.

panelColors?|

Replaces the site's panel colours as a whole: a colour the body leaves out goes back to its default rule, and null clears them all. It applies on the panel's next load and records one site.panel_colors_changed audit entry naming the changed groups, or none when nothing changed. An invalid colour is refused with 400 and nothing is changed. Send it alone to change nothing else.

panelPosition?string

The side the panel docks on. It applies on the next page load of the storefront, with no snippet change, and records one site.panel_display_changed audit entry, or none when nothing changed. null and any other value are refused with 400 and nothing is changed.

Value in

"left"
"right"

panelBackdrop?boolean

true opens the panel with focus on the chat (the page dimmed and paused), false alongside the page. Same rules as panelPosition; sent together, both are recorded in one audit entry.

Response Body

`application/json`

`application/problem+json`

curl -X PATCH "https://example.com/api/v1/sites/string" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Demo Storefront (EU)",
    "platform": "shopify",
    "url": "https://demo-storefront.example.com"
  }'

curl -X PATCH "https://example.com/api/v1/sites/string" \  -H "Content-Type: application/json" \  -d '{    "name": "Demo Storefront (EU)",    "platform": "shopify",    "url": "https://demo-storefront.example.com"  }'

{
  "data": {
    "resumeButton": {
      "position": "left",
      "offsetBottom": 0,
      "offsetSide": 0,
      "offsetBottomNarrow": 0,
      "offsetSideNarrow": 0,
      "colors": {
        "background": "string",
        "icon": "string",
        "border": "string"
      },
      "icon": "sparkle",
      "size": "sm",
      "radius": "none",
      "shadow": "none"
    },
    "id": "string",
    "name": "string",
    "platform": "shopify",
    "url": "string",
    "siteInformation": "string",
    "toneOfVoice": "string",
    "vertical": "string",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z",
    "autoGenerateStarters": true,
    "switchOnGeneratedStarters": true,
    "pageViewCountingEnabled": true,
    "storefrontCartCountingEnabled": true,
    "autoReadPages": true,
    "autoReadMinViews": 0,
    "tagMonitoringEnabled": true,
    "panelColors": {
      "panel": {
        "background": "string"
      },
      "actions": {
        "fill": "string",
        "text": "string",
        "hover": "string",
        "border": "string"
      },
      "visitor": {
        "fill": "string",
        "text": "string"
      },
      "highlights": {
        "fill": "string",
        "text": "string"
      },
      "assistant": {
        "text": "string"
      },
      "links": {
        "color": "string"
      },
      "suggestions": {
        "fill": "string",
        "text": "string",
        "border": "string"
      }
    },
    "panelPosition": "left",
    "panelBackdrop": true,
    "hostedPage": {
      "enabled": true,
      "link": "string"
    },
    "defaultAgentId": "string",
    "analysisState": "running"
  }
}

{  "data": {    "resumeButton": {      "position": "left",      "offsetBottom": 0,      "offsetSide": 0,      "offsetBottomNarrow": 0,      "offsetSideNarrow": 0,      "colors": {        "background": "string",        "icon": "string",        "border": "string"      },      "icon": "sparkle",      "size": "sm",      "radius": "none",      "shadow": "none"    },    "id": "string",    "name": "string",    "platform": "shopify",    "url": "string",    "siteInformation": "string",    "toneOfVoice": "string",    "vertical": "string",    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "autoGenerateStarters": true,    "switchOnGeneratedStarters": true,    "pageViewCountingEnabled": true,    "storefrontCartCountingEnabled": true,    "autoReadPages": true,    "autoReadMinViews": 0,    "tagMonitoringEnabled": true,    "panelColors": {      "panel": {        "background": "string"      },      "actions": {        "fill": "string",        "text": "string",        "hover": "string",        "border": "string"      },      "visitor": {        "fill": "string",        "text": "string"      },      "highlights": {        "fill": "string",        "text": "string"      },      "assistant": {        "text": "string"      },      "links": {        "color": "string"      },      "suggestions": {        "fill": "string",        "text": "string",        "border": "string"      }    },    "panelPosition": "left",    "panelBackdrop": true,    "hostedPage": {      "enabled": true,      "link": "string"    },    "defaultAgentId": "string",    "analysisState": "running"  }}

Update a site

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

400application/problem+json

401application/problem+json

404application/problem+json

429application/problem+json

500application/problem+json

Authorization

Path Parameters

Request Body

Response Body

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`