Site

Site endpoints of the Zanfia Workspace API, with schemas and code samples.

9 min readLast updated Sep 10, 2026

Your workspace's public site (Site → Settings): GET /site/settings returns the whole platformSettings document plus the client-communication base URL; each PATCH /site/settings/{slice} writes ONE atomic slice (general, theme, branding, main-page, privacy, portal, communication, access-policy) through the same use cases the dashboard uses, so omitted fields are never clobbered. POST /site/activate publishes/unpublishes the site. The slug and custom domains are heavier (they touch Stripe, Firebase Auth and Vercel): PATCH /site/slug, PUT /site/domains, then POST /site/domains/verify for the live DNS/TLS state. The storefront layout is a whole-config GET/PUT. Legal documents (terms + privacy policy) use the dashboard's write/link modes: write stores Markdown served at /documents/{slug}, link points at an external URL. Errors: 400 validation-failed / restricted-domain / no-domains-configured, 403 feature-not-available / unauthorized-domain, 404 main-page-not-found, 409 main-page-not-published / slug-taken / domain-taken, 503 not-configured (custom-domain routes on a deployment without Vercel access). All routes require a Authorization: Bearer header — see Authentication.

Get site settings

GET/site/settings

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Response Body

`application/json`

curl -X GET "https://example.com/site/settings"

{  "settings": {    "active": true,    "showPageTitle": true,    "pageTitle": "string",    "pageDescription": "string",    "slug": "string",    "domains": [      "string"    ],    "logoUrl": "string",    "logoDarkUrl": "string",    "platformFaviconUrl": "string",    "logo": {      "url": "string",      "mediaId": "string"    },    "logoDark": {      "url": "string",      "mediaId": "string"    },    "platformFavicon": {      "url": "string",      "mediaId": "string"    },    "theme": null,    "grayScale": null,    "radius": null,    "styleVariant": "solid",    "hideZanfiaBranding": true,    "mainPage": "/",    "mainPageId": "string",    "mainPageCommunityId": "string",    "cookieConsentEnabled": true,    "customColors": {      "light": {        "accent": "string",        "gray": "string",        "background": "string"      },      "dark": {        "accent": "string",        "gray": "string",        "background": "string"      }    },    "customCheckoutColors": {      "light": {        "checkoutLeftBackground": "string",        "checkoutRightBackground": "string",        "checkoutLeftTextColor": "string",        "checkoutLeftPriceColor": "string",        "accent": "string"      },      "dark": {        "checkoutLeftBackground": "string",        "checkoutRightBackground": "string",        "checkoutLeftTextColor": "string",        "checkoutLeftPriceColor": "string",        "accent": "string"      }    },    "customCheckoutTheme": {      "theme": "tomato",      "grayScale": "auto",      "radius": "none",      "styleVariant": "solid",      "customColors": {        "light": {          "accent": "string",          "gray": "string",          "background": "string"        },        "dark": {          "accent": "string",          "gray": "string",          "background": "string"        }      }    },    "selectedTheme": "light",    "language": "pl",    "portalCustomization": {      "libraryWidth": "full",      "libraryLayout": "grid",      "mobileLibraryLayout": "grid",      "libraryOrder": "newest",      "libraryCustomOrder": [        "string"      ],      "libraryGroupByType": true,      "defaultView": "library",      "messagesEnabled": true,      "clientMessagesEnabled": true    },    "customerAccessPolicy": {      "activeDeviceLimit": 0,      "replacementStrategy": "adaptive",      "version": "string"    },    "typography": {      "headingFamily": "string",      "bodyFamily": "string"    },    "themeFromBrand": true  },  "communication": {    "baseUrl": {      "type": "app"    }  }}

{  "error": "string",  "message": "string"}

Update general site settings

PATCH/site/settings/general

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

PATCH /site/settings/general — every field optional; an omitted field keeps its stored value (the shared use case leaves undefined slots untouched).

pageTitle?string|null

pageDescription?string|null

showPageTitle?boolean

language?PlatformLanguage

Value in

"pl"
"en"
"default"

mainPage?MainPlatformPage

Value in

"/"
"/dashboard"
"/community"

mainPageId?|

When set (and mainPage === MainPlatformPage.Sales), the storefront root renders this custom Page's HTML instead of the product grid. Holds a PageDocument.id. Null/absent → product storefront. The page must be Published to render; otherwise the root falls back to the product storefront.

mainPageCommunityId?|

When mainPage === MainPlatformPage.Community, the storefront root redirects to this community's member page (/app/community/{slug}). Holds a Community.id. A public community renders its guest view to anonymous visitors; a private one shows the login page. Ignored for other mainPage values. Null/absent while Community is selected → root falls back to the portal home resolver (/app/home).

Response Body

`application/json`

curl -X PATCH "https://example.com/site/settings/general" \  -H "Content-Type: application/json" \  -d '{}'

{  "status": "ok"}

{  "error": "string",  "message": "string"}

Update site theme

PATCH/site/settings/theme

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

theme?null|

grayScale?null|

radius?null|

styleVariant?PlatformStyleVariant

Value in

"solid"
"classic"

customColors?|null

customCheckoutTheme?|null

typography?|null

themeFromBrand?boolean

Theme follows the brand: when true, the landing derives the accent color and typography from the workspace's PRIMARY brand profile at read time (customColors/typography above become a fallback snapshot). Changing the brand ripples to the site without re-saving the theme.

Response Body

`application/json`

curl -X PATCH "https://example.com/site/settings/theme" \  -H "Content-Type: application/json" \  -d '{}'

{  "status": "ok"}

{  "error": "string",  "message": "string"}

Update site branding

PATCH/site/settings/branding

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

logoUrl?|

Legacy flat URL — still the source readers consume. Writers must keep this in sync with logo.

logo?|

Canonical Media Library reference — dual-written alongside logoUrl during migration.

logoDarkUrl?|

Legacy flat URL — still the source readers consume. Writers must keep this in sync with logoDark.

logoDark?|

Canonical Media Library reference — dual-written alongside logoDarkUrl during migration.

platformFaviconUrl?|

Legacy flat URL — still the source readers consume. Writers must keep this in sync with platformFavicon.

platformFavicon?|

Canonical Media Library reference — dual-written alongside platformFaviconUrl during migration.

hideZanfiaBranding?boolean

Hide the "Powered by Zanfia" badge on checkouts/pages. Branding is ON by default for every workspace (absent/false → badge shown) — this opt-out only takes effect while the plan (or a manual grant) carries remove_branding: readers must AND it with the feature check, and the write path asserts the feature server-side.

Response Body

`application/json`

curl -X PATCH "https://example.com/site/settings/branding" \  -H "Content-Type: application/json" \  -d '{}'

{  "status": "ok"}

{  "error": "string",  "message": "string"}

Set the storefront root page

PATCH/site/settings/main-page

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Sets the storefront root: mainPage (sales vs dashboard) + mainPageId (the custom Page rendered at root, or null for the product storefront). When a non-null mainPageId is sent the use case verifies the page is Published.

mainPage?MainPlatformPage

Value in

"/"
"/dashboard"
"/community"

mainPageId?|

Response Body

`application/json`

curl -X PATCH "https://example.com/site/settings/main-page" \  -H "Content-Type: application/json" \  -d '{}'

{  "status": "ok"}

{  "error": "string",  "message": "string"}

PATCH/site/settings/privacy

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

cookieConsentEnabled?boolean

Response Body

`application/json`

curl -X PATCH "https://example.com/site/settings/privacy" \  -H "Content-Type: application/json" \  -d '{}'

{  "status": "ok"}

{  "error": "string",  "message": "string"}

Update client-area customization

PATCH/site/settings/portal

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

portalCustomization?|null

Response Body

`application/json`

curl -X PATCH "https://example.com/site/settings/portal" \  -H "Content-Type: application/json" \  -d '{}'

{  "status": "ok"}

{  "error": "string",  "message": "string"}

Update client communication base URL

PATCH/site/settings/communication

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Workspace-level client communication settings (workspaces/{wid}. clientsCommunicationSettings) — a sibling of platformSettings, not part of it. Holds the base URL used to build the links sent to customers.

baseUrl*|

Response Body

`application/json`

curl -X PATCH "https://example.com/site/settings/communication" \  -H "Content-Type: application/json" \  -d '{    "baseUrl": {      "type": "app"    }  }'

{  "status": "ok"}

{  "error": "string",  "message": "string"}

Update the customer device policy

PATCH/site/settings/access-policy

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

customerAccessPolicy*|

version is minted by the server and can never be supplied by a client.

Response Body

`application/json`

curl -X PATCH "https://example.com/site/settings/access-policy" \  -H "Content-Type: application/json" \  -d '{    "customerAccessPolicy": {      "activeDeviceLimit": 0    }  }'

{  "status": "ok"}

{  "error": "string",  "message": "string"}

Publish or unpublish the site

POST/site/activate

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Sets the platform "published/live" flag (platformSettings.active). A dedicated atomic endpoint: activation used to be forced on every legacy settings save; onboarding completion now sets it explicitly as its final step.

active?boolean

Response Body

`application/json`

curl -X POST "https://example.com/site/activate" \  -H "Content-Type: application/json" \  -d '{}'

{  "status": "ok"}

{  "error": "string",  "message": "string"}

Change the site slug

PATCH/site/slug

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Heavy slice — slug carries Stripe/Firebase/Vercel + cache/routing side effects.

slug?string

Response Body

`application/json`

curl -X PATCH "https://example.com/site/slug" \  -H "Content-Type: application/json" \  -d '{}'

{  "status": "ok"}

{  "error": "string",  "message": "string"}

Replace the custom domains

PUT/site/domains

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Heavy slice — custom domains carry Stripe/Firebase/Vercel + cache side effects.

domains?array<string>

Response Body

`application/json`

curl -X PUT "https://example.com/site/domains" \  -H "Content-Type: application/json" \  -d '{}'

{  "status": "ok"}

{  "error": "string",  "message": "string"}

Verify custom domains

POST/site/domains/verify

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

domains*array<string>

Response Body

`application/json`

curl -X POST "https://example.com/site/domains/verify" \  -H "Content-Type: application/json" \  -d '{    "domains": [      "string"    ]  }'

{  "results": [    {      "domain": "string",      "status": "verified",      "ssl": {        "state": "active",        "issuer": "string",        "validTo": "string"      }    }  ]}

{  "error": "string",  "message": "string"}

Get the storefront layout

GET/site/storefront

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Response Body

`application/json`

curl -X GET "https://example.com/site/storefront"

{  "sections": [    {      "id": "string",      "title": "string",      "description": "string",      "layout": "grid",      "mode": "manual",      "productIds": [        "string"      ],      "rule": {        "type": "allPublic",        "productType": "course",        "tag": "string"      },      "sort": "newest"    }  ],  "layout": "grid",  "columns": 0,  "preset": "platform",  "mode": "light",  "overrides": {    "accentColor": "string",    "colors": {      "light": {        "paper": "string",        "card": "string",        "ink": "string",        "accent": "string"      },      "dark": {        "paper": "string",        "card": "string",        "ink": "string",        "accent": "string"      }    },    "fontDisplay": "platform",    "fontBody": "platform",    "cardRadius": 0,    "imageRatio": "default",    "showBadge": true,    "showPrices": true,    "showSocialProof": true,    "descriptionLines": 0  },  "looseProductOrder": [    "string"  ],  "heading": "string",  "subheading": "string",  "footer": {    "showLegalLinks": true,    "contact": {      "businessName": "string",      "address": "string",      "email": "string",      "phone": "string",      "extraInfo": "string"    },    "socialLinks": [      {        "network": "facebook",        "url": "string"      }    ],    "customLinks": [      {        "id": "string",        "label": "string",        "url": "string"      }    ],    "copyrightText": "string"  }}

{  "error": "string",  "message": "string"}

Replace the storefront layout

PUT/site/storefront

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Full-replace of the storefront config (the manager holds the whole state).

sections*array<>

layout?StoreSectionLayout

Visual layout of a storefront section on the public store page.

Only Grid is wired end-to-end in the first storefront-management slice; the others are defined up front so the data model is stable, and wired into the renderer in a later phase.

Value in

"grid"
"featuredHero"
"carousel"
"list"

columns?number

preset?StorefrontPreset

Predefined visual style of the whole public storefront. Each preset maps to a set of theme tokens (fonts, colors, radii) in the landing renderer.

Value in

"platform"
"editorial"
"modern"
"playful"

mode?StorefrontThemeMode

Color-scheme mode of the public storefront. Unset = the preset's native scheme (Modern is natively dark, the others light), preserving stores saved before the mode existed.

Value in

"light"
"dark"
"auto"

overrides?

Creator overrides layered on top of the chosen preset's theme tokens. Every field is optional — an absent field keeps the preset's value, so switching presets never loses the creator's explicit choices.

looseProductOrder?array<string>

heading?string

subheading?string

footer?

Creator customization of the public-storefront footer. Every field is optional — an absent config renders the minimal default footer (brand name, year, and the auto legal links when legal content exists).

Response Body

`application/json`

curl -X PUT "https://example.com/site/storefront" \  -H "Content-Type: application/json" \  -d '{    "sections": [      {        "id": "string",        "title": "string",        "layout": "grid",        "mode": "manual"      }    ]  }'

{  "sections": [    {      "id": "string",      "title": "string",      "description": "string",      "layout": "grid",      "mode": "manual",      "productIds": [        "string"      ],      "rule": {        "type": "allPublic",        "productType": "course",        "tag": "string"      },      "sort": "newest"    }  ],  "layout": "grid",  "columns": 0,  "preset": "platform",  "mode": "light",  "overrides": {    "accentColor": "string",    "colors": {      "light": {        "paper": "string",        "card": "string",        "ink": "string",        "accent": "string"      },      "dark": {        "paper": "string",        "card": "string",        "ink": "string",        "accent": "string"      }    },    "fontDisplay": "platform",    "fontBody": "platform",    "cardRadius": 0,    "imageRatio": "default",    "showBadge": true,    "showPrices": true,    "showSocialProof": true,    "descriptionLines": 0  },  "looseProductOrder": [    "string"  ],  "heading": "string",  "subheading": "string",  "footer": {    "showLegalLinks": true,    "contact": {      "businessName": "string",      "address": "string",      "email": "string",      "phone": "string",      "extraInfo": "string"    },    "socialLinks": [      {        "network": "facebook",        "url": "string"      }    ],    "customLinks": [      {        "id": "string",        "label": "string",        "url": "string"      }    ],    "copyrightText": "string"  }}

{  "error": "string",  "message": "string"}

Get legal documents

GET/site/legal-documents

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Query Parameters

language?"pl"

Default"pl"

Value in

"pl"

Response Body

`application/json`

curl -X GET "https://example.com/site/legal-documents"

{  "language": "pl",  "termsContent": "string",  "termsUrl": "string",  "termsSlug": "string",  "privacyPolicyContent": "string",  "privacyPolicyUrl": "string",  "privacyPolicySlug": "string"}

{  "error": "string",  "message": "string"}

Update legal documents

PATCH/site/legal-documents

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

PATCH /site/legal-documents — patch one or both documents.

language?AvailableLang

Defaults to pl (the only supported value today).

terms?

One legal document patch. write stores Markdown content on the site (served at /documents/{slug}) and blanks the external URL; link points the document at an external url and blanks the stored content — exactly the dashboard's two modes. slug (write mode) customizes the public path; it is normalized to URL-safe kebab-case. Omitted fields keep their value.

privacyPolicy?

Response Body

`application/json`

curl -X PATCH "https://example.com/site/legal-documents" \  -H "Content-Type: application/json" \  -d '{}'

{  "language": "pl",  "termsContent": "string",  "termsUrl": "string",  "termsSlug": "string",  "privacyPolicyContent": "string",  "privacyPolicyUrl": "string",  "privacyPolicySlug": "string"}

{  "error": "string",  "message": "string"}

Was this article helpful?

Spotted something off? Tell us at support@zanfia.com.

Get site settings

200application/json

4XXapplication/json

Update general site settings

200application/json

4XXapplication/json

Update site theme

200application/json

4XXapplication/json

Update site branding

200application/json

4XXapplication/json

Set the storefront root page

200application/json

4XXapplication/json

Update cookie consent

200application/json

4XXapplication/json

Update client-area customization

200application/json

4XXapplication/json

Update client communication base URL

200application/json

4XXapplication/json

Update the customer device policy

200application/json

4XXapplication/json

Publish or unpublish the site

200application/json

4XXapplication/json

Change the site slug

200application/json

4XXapplication/json

Replace the custom domains

200application/json

4XXapplication/json

Verify custom domains

200application/json

4XXapplication/json

Get the storefront layout

200application/json

4XXapplication/json

Replace the storefront layout

200application/json

4XXapplication/json

Get legal documents

200application/json

4XXapplication/json

Update legal documents

200application/json

4XXapplication/json

Related articles

API overview

Authentication and API keys

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`