List global documents

import { createSiteClient } from '@fetchski/attract-cms-sdk';

const site = createSiteClient();
const globalList = await site.globalContent().listGlobalContent();

{
  "results": [
    {
      "_id": "global",
      "slug": "global",
      "type": "@apostrophecms/global",
      "cookiePolicyVersion": "1",
      "cookieMessage": "This website uses cookies to supplement a balanced diet and provide a much deserved reward to the senses after consuming bland but nutritious meals. Accepting our cookies is optional but recommended, as they are delicious.",
      "cookieAcceptLabel": "Accept all",
      "cookieRejectLabel": "Reject all",
      "cookiePrefsTitle": "Cookie preferences",
      "createdAt": "2026-10-24T09:30:00.000Z",
      "updatedAt": "2026-10-24T09:30:00.000Z"
    }
  ],
  "pages": 1,
  "currentPage": 1
}

import { createSiteClient } from '@fetchski/attract-cms-sdk';

const site = createSiteClient();
const globalList = await site.globalContent().listGlobalContent();

{
  "results": [
    {
      "_id": "global",
      "slug": "global",
      "type": "@apostrophecms/global",
      "cookiePolicyVersion": "1",
      "cookieMessage": "This website uses cookies to supplement a balanced diet and provide a much deserved reward to the senses after consuming bland but nutritious meals. Accepting our cookies is optional but recommended, as they are delicious.",
      "cookieAcceptLabel": "Accept all",
      "cookieRejectLabel": "Reject all",
      "cookiePrefsTitle": "Cookie preferences",
      "createdAt": "2026-10-24T09:30:00.000Z",
      "updatedAt": "2026-10-24T09:30:00.000Z"
    }
  ],
  "pages": 1,
  "currentPage": 1
}

In your app

A function makes the call on the client it is given, so your code passes the real one and a test passes a fake.

Add the function

src/attract/list-global-content.ts

import type { SiteClient } from '@fetchski/attract-cms-sdk';

export async function listGlobalContent(site: SiteClient) {
  return site.globalContent().listGlobalContent();
}

Call it

A script makes the client once and calls the function:

scripts/list-global-content.ts

import { createSiteClient } from '@fetchski/attract-cms-sdk';
import { listGlobalContent } from '../src/attract/list-global-content.ts';

const site = createSiteClient();
console.log(await listGlobalContent(site));

Terminal

node --env-file=.env scripts/list-global-content.ts

A route handler, a job or a queue worker calls it the same way.

Optional parameters

One object, e.g. listGlobalContent({ aposMode }); leave out the optional fields.

AposMode | null | undefined

Optional. Leave it out and the site uses "published". published (the default) or draft. Drafts need a credential that may see them: an API key with the type’s write scope (content:<type>:write), or a signed-in editor. The public and a key with only the read scope get 403. One of draft, published.

string | null | undefined

Optional. Leave it out (or pass null) and it isn’t sent: the site’s default applies. The locale to read or write, e.g. en (default: the site’s default locale).

number | null | undefined

Optional. Leave it out and the site uses 1. Page number for pagination (1-based)

number | null | undefined

Optional. Leave it out (or pass null) and it isn’t sent: the site’s default applies. Documents per page. Each content type has its own default (core’s is 50; a type may set another). There is no upper limit: a large value answers the whole list at once, which is slow on a big one. At least 1.

string | null | undefined

Optional. Leave it out (or pass null) and it isn’t sent: the site’s default applies. Matches documents by their text. Ignored for the public and API keys on a type whose public fields leave some out (a search would match the hidden ones).

boolean | null | undefined

Optional. Leave it out and the site uses false. true: each area’s widgets come back rendered as HTML (_rendered), beside their data.

string | null | undefined

Optional. Leave it out (or pass null) and it isn’t sent: the site’s default applies. Only the document with exactly this slug: a list of one, or an empty list when none has it. Use it to find a document by the name in its URL.

Returns

A GlobalList. A page of Global documents. Read its properties (globalList.results): each says whether the site always sends it. The example answer is the site’s wire JSON: some keys differ from the property names (_id → id, _logo → logo, _logoLight → logoLight …).

readonly GlobalContent[]

Always sent. A list of GlobalContent. This page’s documents; empty past the last page.

Show GlobalContent

The site-wide settings document (one per site and locale), with the fields this site adds.

string

Always sent. Unique identifier.

string

Always sent. Default slug field.

string

Always sent.

Always sent. Change this — to “2”, a date, anything — and every visitor is asked again. Do that whenever what you do with the data materially changes; consent given under the old terms does not carry over.

Always sent. Banner message.

Always sent. Accept button.

Always sent. Give this the same visual weight as Accept. A reject option that is harder to find than accept is the single most commonly penalized banner design.

Always sent. Preferences panel heading.

Date

Always sent. Created At. Format: an ISO 8601 date and time.

Date

Always sent. Updated At. Format: an ISO 8601 date and time.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Default title field.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. The _id of the piece/page that was copied to create this document (only present if created via _copyingId)

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Business name.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Tagline.

readonly Readonly<Record<string, unknown>>[] | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Shown in the site header on the dark theme (and over the hero). Upload to the Images library first. The related @apostrophecms/image documents, in order (empty when none). To set it, send a list of { "_id": "…" }, one per document (one at most); a document the site can’t find is left out. At most 1 items.

readonly Readonly<Record<string, unknown>>[] | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Optional darker logo for the light theme. If empty, the white logo is auto-inverted. The related @apostrophecms/image documents, in order (empty when none). To set it, send a list of { "_id": "…" }, one per document (one at most); a document the site can’t find is left out. At most 1 items.

readonly Readonly<Record<string, unknown>>[] | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Browser tab icon — the default, also used when the browser is in dark mode. Upload a square PNG or SVG (at least 64×64) to the Images library. If empty, the bundled default icon is used. The related @apostrophecms/image documents, in order (empty when none). To set it, send a list of { "_id": "…" }, one per document (one at most); a document the site can’t find is left out. At most 1 items.

readonly Readonly<Record<string, unknown>>[] | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Optional. Used when the visitor’s BROWSER or device is in light mode — this follows the browser’s color scheme, not the site’s own theme toggle. If empty, the main favicon is used everywhere. The related @apostrophecms/image documents, in order (empty when none). To set it, send a list of { "_id": "…" }, one per document (one at most); a document the site can’t find is left out. At most 1 items.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Shown in the footer. Use up to three lines for a full street address, or just one for a town/region.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Address line 2.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Address line 3.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Phone.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Email.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. The registered name of the company, e.g. “Example Holdings LLC”. Fills [Business legal name].

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Any other names the business operates under, e.g. “Example Studio and Example Supply”. Fills [Trade names].

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Where the business is based, for governing law. Fills [State or region].

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Fills [Country].

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Where legal disputes are heard. Fills [County or venue].

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. The youngest age your website is intended for, e.g. “13”. Fills [Minimum age].

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Your main brand color — buttons, links, accents. Hover + soft tints are derived automatically. Leave empty for the built-in design color.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. A CSS color (#625bff, #625bffff, rgb(…), hsl(…), a color name) or a palette token’s name (--fetchski-accent).

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Text/icon color shown ON primary-colored buttons. Defaults to white — set a dark color if your primary is pale.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Supporting color — eyebrows, offset shadows, secondary accents.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Warm accent, used sparingly.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Body-text link color (rich-text content). Leave empty to track the primary color.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. The base page background.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Cards and raised panels that sit above the page background.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Recessed / inset bands.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Primary text color. Mind contrast against the page background.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Secondary / muted text color.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Borders and dividers.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Positive / confirmation state (forms, alerts).

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Caution state.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Error / destructive state.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Informational state.

string | null

FontDisplaySource | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Typeface used for headings and display type. Default is the built-in design font; the other sources replace it site-wide. One of default, curated, cdn, upload; a newer site may send others, so keep a fallback.

FontDisplayCurated | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Display font — curated pick. One of clash-display, satoshi, general-sans, space-grotesk, bricolage-grotesque, archivo, sora, syne, outfit, unbounded, fraunces, playfair-display, zodiak, sentient; a newer site may send others, so keep a fallback.

FontDisplayCdnProvider | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Where to browse for the family. Pick one, then follow the link below to find the exact name. One of bunny, fontshare; a newer site may send others, so keep a fallback.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Exactly as the provider’s catalog spells it, e.g. “Space Grotesk” or “Clash Display”.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Comma-separated weights to load, e.g. 400, 700. Empty loads 500, 700, 800. Weights the family doesn’t ship are skipped by the CDN and synthesized by the browser (faux bold).

readonly GlobalFontDisplayUploadsItem[] | null

Sometimes sent: undefined when the site leaves it out, and it can be null. A list of GlobalFontDisplayUploadsItem. One file per weight/style of the SAME typeface. woff2 strongly recommended (smallest, universally supported); woff/ttf/otf also accepted. At most 8 items.

Show GlobalFontDisplayUploadsItem

Readonly<Record<string, unknown>>

Always sent. File attachment reference.

string

Sometimes sent: undefined when the site leaves it out. The row’s id, unique in its array.

Weight | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Weight. One of 100, 200, 300, 400, 500, 600, 700, 800, 900; a newer site may send others, so keep a fallback.

Style | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Style. One of normal, italic; a newer site may send others, so keep a fallback.

Readonly<Record<string, unknown>>

Always there: {} when there are none. Any keys the site sent that aren’t listed above (such as one added after this SDK was built), by their wire names, as sent. Pass this model to a write and they are sent too.

FontDisplayFallback | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Generic system fonts shown while the font loads (and if it fails). Curated picks set this automatically. One of sans, serif, mono; a newer site may send others, so keep a fallback.

FontBodySource | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Typeface used for body text and UI. Default is the built-in design font; the other sources replace it site-wide. One of default, curated, cdn, upload; a newer site may send others, so keep a fallback.

FontBodyCurated | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Body font — curated pick. One of inter, manrope, public-sans, work-sans, nunito-sans, ibm-plex-sans, source-sans-3, dm-sans, karla, switzer, supreme, satoshi, general-sans, lora, source-serif-4; a newer site may send others, so keep a fallback.

FontBodyCdnProvider | null

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Exactly as the provider’s catalog spells it, e.g. “Space Grotesk” or “Clash Display”.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Comma-separated weights to load, e.g. 400, 700. Empty loads 400, 500, 600, 700. Weights the family doesn’t ship are skipped by the CDN and synthesized by the browser (faux bold).

readonly GlobalFontBodyUploadsItem[] | null

Sometimes sent: undefined when the site leaves it out, and it can be null. A list of GlobalFontBodyUploadsItem. One file per weight/style of the SAME typeface. woff2 strongly recommended (smallest, universally supported); woff/ttf/otf also accepted. At most 8 items.

Show GlobalFontBodyUploadsItem

Readonly<Record<string, unknown>>

Always sent. File attachment reference.

string

Sometimes sent: undefined when the site leaves it out. The row’s id, unique in its array.

Weight | null

Style | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Style. One of normal, italic; a newer site may send others, so keep a fallback.

Readonly<Record<string, unknown>>

FontBodyFallback | null

FontAccentSource | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Typeface used for code blocks and monospace accents. Default is the built-in design font; the other sources replace it site-wide. One of default, curated, cdn, upload; a newer site may send others, so keep a fallback.

FontAccentCurated | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Accent / mono font — curated pick. One of jetbrains-mono, ibm-plex-mono, fira-code, space-mono, source-code-pro, dm-mono, inconsolata, ubuntu-mono, courier-prime, red-hat-mono, spline-sans-mono, victor-mono; a newer site may send others, so keep a fallback.

FontAccentCdnProvider | null

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Exactly as the provider’s catalog spells it, e.g. “Space Grotesk” or “Clash Display”.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Comma-separated weights to load, e.g. 400, 700. Empty loads 400, 700. Weights the family doesn’t ship are skipped by the CDN and synthesized by the browser (faux bold).

readonly GlobalFontAccentUploadsItem[] | null

Sometimes sent: undefined when the site leaves it out, and it can be null. A list of GlobalFontAccentUploadsItem. One file per weight/style of the SAME typeface. woff2 strongly recommended (smallest, universally supported); woff/ttf/otf also accepted. At most 8 items.

Show GlobalFontAccentUploadsItem

Readonly<Record<string, unknown>>

Always sent. File attachment reference.

string

Sometimes sent: undefined when the site leaves it out. The row’s id, unique in its array.

Weight | null

Style | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Style. One of normal, italic; a newer site may send others, so keep a fallback.

Readonly<Record<string, unknown>>

FontAccentFallback | null

ContentWidth | null

Sometimes sent: undefined when the site leaves it out, and it can be null. The widest the page content gets: sections, layouts, the header and the footer all line up to it. Smaller screens always use their full width, minus the side margins. One of standard, wide, xwide; a newer site may send others, so keep a fallback.

Sometimes sent: undefined when the site leaves it out, and it can be null. A list of GlobalSocialLinksItem. Each profile is optional — add only the networks you use. A link only appears once it has a URL. Pick a platform for its brand icon, or “Other / custom” to choose any icon.

Show GlobalSocialLinksItem

Platform

Always sent. Platform. One of instagram, facebook, x-twitter, youtube, tiktok, linkedin, github, pinterest, whatsapp, snapchat, threads, bluesky, mastodon, yelp, google, spotify, vimeo, custom; a newer site may send others, so keep a fallback.

string

Always sent. Full link to the profile, e.g. https://instagram.com/yourbusiness. Format: an absolute URL.

string

Sometimes sent: undefined when the site leaves it out. The row’s id, unique in its array.

string

Sometimes sent: undefined when the site leaves it out. Overrides the screen-reader / tooltip label. Recommended for a custom platform — defaults to the icon name (e.g. “discord” → “Discord”).

string

Sometimes sent: undefined when the site leaves it out. Font Awesome icon name (no “fa-” prefix), e.g. discord. Browse fontawesome.com/icons.

IconFamily | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Custom icon family. One of classic-regular, duotone-regular, brands, jelly, jelly-duo, whiteboard; a newer site may send others, so keep a fallback.

Readonly<Record<string, unknown>>

ImageArea

Sometimes sent: undefined when the site leaves it out. An ImageArea. Site-wide fallback for link previews (Open Graph): used on any page that has neither its own Social share image nor a featured image. Recommended 1200×630. Widgets, top to bottom: send { "items": [ … ] }, one object per widget with its type. Writing it replaces the whole area.

Show ImageArea

Widgets, top to bottom: send { "items": [ … ] }, one object per widget with its type. Writing it replaces the whole area.

AfterContentAreaMetaType

Sometimes sent: undefined when the site leaves it out. Always area. One of area; a newer site may send others, so keep a fallback.

string

Sometimes sent: undefined when the site leaves it out. The area’s id, set by the site: leave it out when you write one.

readonly ImageWidget[]

Sometimes sent: undefined when the site leaves it out. A list of ImageWidget. The widgets, top to bottom. Each is an object with its type and that widget’s own fields; _id and metaType may be left out (the site sets them). At most 1 items.

Show ImageWidget

A @apostrophecms/image widget: its type and its own fields. A field left out takes its default.

ImageWidgetType

Always sent. The widget’s type: always @apostrophecms/image. One of @apostrophecms/image; a newer site may send others, so keep a fallback.

string

Sometimes sent: undefined when the site leaves it out. The widget’s id, unique on the page. Leave it out for a new widget (the site sets one); keep it to change a widget that is there.

MetaType

Sometimes sent: undefined when the site leaves it out. Always widget. One of widget; a newer site may send others, so keep a fallback.

readonly Readonly<Record<string, unknown>>[]

Sometimes sent: undefined when the site leaves it out. The related @apostrophecms/image documents, in order (empty when none). To set it, send a list of { "_id": "…" }, one per document (one at most); a document the site can’t find is left out. At most 1 items.

string

Sometimes sent: undefined when the site leaves it out. Caption.

LinkTo | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Link To… One of none, @apostrophecms/any-page-type, _url; a newer site may send others, so keep a fallback.

readonly Readonly<Record<string, unknown>>[]

Sometimes sent: undefined when the site leaves it out. The related @apostrophecms/any-page-type documents, in order (empty when none). To set it, send a list of { "_id": "…" }, one per document (one at most); a document the site can’t find is left out. At most 1 items.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. apostrophe:linkHrefHelp When set, a URL; empty or null when not.

string

Sometimes sent: undefined when the site leaves it out. Link Title.

string

Sometimes sent: undefined when the site leaves it out. If empty, the title of the related document will be used.

readonly LinkTarget[] | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Link Target. Each one of _blank.

CustomCSS | null

Sometimes sent: undefined when the site leaves it out, and it can be null. A CustomCSS. CSS for this one section, typed into the slot of the part it styles. It wins over Site design → Custom CSS. Nested rules like &:hover, @media (width >= 48rem) and [data-theme=“light”] & work inside a slot.

Show CustomCSS

Readonly<Record<string, string>>

Sometimes sent: undefined when the site leaves it out. The CSS typed into each part slot, by slot name.

string

Sometimes sent: undefined when the site leaves it out. The compiled CSS (read only: rebuilt from slots).

string

Sometimes sent: undefined when the site leaves it out. The site’s check mark for css (read only).

Readonly<Record<string, unknown>>

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Adds schema.org structured data about the business to every page, built from the Brand tab’s business name, address, phone and email plus the Social Links list. Helps search engines show rich results. Nothing is published until this is on and a business name is set.

SeoStructuredDataType | null

Sometimes sent: undefined when the site leaves it out, and it can be null. The schema.org type that best describes the business. “Local business” fits most sites with a physical location or service area. One of LocalBusiness, Organization, ProfessionalService, Store; a newer site may send others, so keep a fallback.

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Adds the Service Area Map’s coverage (place names, service radius) to the business structured data on every page, and the full zip-code/boundary detail on pages with a Service Area Map section. Helps search engines and AI answers understand where the business serves — there is no visual search result for this, and it never affects map-pack ranking. Keep it consistent with the areas on the business’s Google Business Profile. Demo map data is never published.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Optional, plain words — e.g. “House cleaning” or “Airport transfers”. When set, the structured data pairs it with the service areas as a schema.org Service; when empty the areas attach directly to the business.

AnalyticsProvider | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Plausible is a privacy-friendly, cookieless analytics service. Visitor page views are counted anonymously; logged-in editors are never tracked. One of none, plausible; a newer site may send others, so keep a fallback.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Paste the script address from your site’s snippet in Plausible → Site Settings → Site Installation (it looks like https://plausible.io/js/pa-XXXXXXXX.js and is unique per site). Analytics stay off until this is set. Optional measurements (outbound links, file downloads, form submissions) are toggled in the Plausible dashboard — no change needed here. When set, a URL; empty or null when not.

Sometimes sent: undefined when the site leaves it out, and it can be null. Off hides the banner AND stops every non-essential cookie and third-party embed — declining is the only safe reading of “never asked”. Turn it off only on a site that sets nothing beyond the strictly necessary.

Sometimes sent: undefined when the site leaves it out, and it can be null. Where opt-in applies, nothing non-essential runs until the visitor agrees. Everyone else sees the same banner as a notice: analytics and embedded content work immediately, and declining switches them off. The first option follows the law that is strictest about being asked first, without putting a wall in front of visitors whose law does not require one. One of eu, all, notice; a newer site may send others, so keep a fallback.

Sometimes sent: undefined when the site leaves it out, and it can be null. Country comes from your CDN or proxy (Cloudflare’s header, or one you configure). Without it the site falls back to this, plus a browser time-zone check that quietly upgrades an apparently European visitor to opt-in. Put Cloudflare or a GeoIP header in front of the site and this setting stops mattering. One of lenient, strict; a newer site may send others, so keep a fallback.

Sometimes sent: undefined when the site leaves it out, and it can be null. Banner position. One of left, right, center, full; a newer site may send others, so keep a fallback.

Sometimes sent: undefined when the site leaves it out, and it can be null. Opens the per-category preferences panel. Leaving it on is the safer choice: accept-or-reject with no middle option is what regulators have been fining sites over.

Sometimes sent: undefined when the site leaves it out, and it can be null. A small button pinned to the bottom corner, over the page. Off by default because the footer link below already offers this — turn it on if you want the control visible without scrolling.

Sometimes sent: undefined when the site leaves it out, and it can be null. Puts the reopen control at the bottom of every page, under the “Powered by” line — where visitors look for it. Uses the reopen label from the Cookie banner wording tab. Leave this on unless the floating button above is on instead: consent must stay as easy to withdraw as it was to give.

Sometimes sent: undefined when the site leaves it out, and it can be null. GPC is a browser-level “do not sell or share my data” signal, legally binding in several US states. When on, a visitor sending it starts with everything non-essential switched off — they can still turn categories on by hand.

Sometimes sent: undefined when the site leaves it out, and it can be null. A third-party script that has already run cannot be switched off in place: it keeps running until the next full page load (each vendor is still told about the withdrawal straight away). On, the page reloads as soon as a visitor switches a category OFF, so nothing they declined keeps running. Off by default: the reload interrupts whatever the visitor was doing, and most visitors are not in a region that requires it.

Sometimes sent: undefined when the site leaves it out, and it can be null. How long a visitor’s answer stands before the banner returns. Six months is the common practice and twelve is the usual ceiling. 1 to 365.

Sometimes sent: undefined when the site leaves it out, and it can be null. Stores a receipt for each decision (which categories, when, under which policy version) so you can show consent was given. Kept for two years, then deleted automatically.

Sometimes sent: undefined when the site leaves it out, and it can be null. Optional. Leave empty for the message alone, which is how most banners read best.

Sometimes sent: undefined when the site leaves it out, and it can be null. Rendered after the message as a link to the policy page. Leave empty to omit it.

Sometimes sent: undefined when the site leaves it out, and it can be null. A path on this site or a full URL. The default matches the parked Cookie Policy page.

Sometimes sent: undefined when the site leaves it out, and it can be null. Customize button.

Sometimes sent: undefined when the site leaves it out, and it can be null. Save-choices button.

Sometimes sent: undefined when the site leaves it out, and it can be null. Reopen control label.

Sometimes sent: undefined when the site leaves it out, and it can be null. Preferences panel intro.

Sometimes sent: undefined when the site leaves it out, and it can be null. Strictly necessary — label.

Sometimes sent: undefined when the site leaves it out, and it can be null. Shown beside this category’s switch in the preferences panel. Say what the visitor gains or loses, not which vendors are involved.

Sometimes sent: undefined when the site leaves it out, and it can be null. Functional — label.

Sometimes sent: undefined when the site leaves it out, and it can be null. Analytics — label.

Sometimes sent: undefined when the site leaves it out, and it can be null. Marketing — label.

Sometimes sent: undefined when the site leaves it out, and it can be null. Shown in place of an embed (a map, a social video) that is waiting on consent.

Sometimes sent: undefined when the site leaves it out, and it can be null. Blocked-content message.

Sometimes sent: undefined when the site leaves it out, and it can be null. Blocked-content button.

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Takes the public site offline. Visitors and search engines see a “be right back” page (served with the correct temporary-outage signals, so search rankings are preserved); logged-in editors keep the full site and can continue editing. A new site starts with this on: turn it off when the site is ready to go live.

MaintenanceRetryAfter | null

Sometimes sent: undefined when the site leaves it out, and it can be null. How long search engines should wait before checking back (the Retry-After hint). A rough estimate is fine — it is a hint, not a promise, and nothing switches back automatically. One of 3600, 14400, 43200, 86400, 259200, 604800; a newer site may send others, so keep a fallback.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Optional short message shown on the maintenance page (e.g. what is happening or when you expect to be back). Leave empty for a generic “we’ll be back soon” line.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Public reCAPTCHA v3 site key. Managed automatically from Connections → Spam protection — edit it there, not here.

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Whether anonymous page views are being recorded. Managed automatically from Visitor data → Request log — edit it there, not here.

Sometimes sent: undefined when the site leaves it out, and it can be null. Whether anonymous visitors get the first-party visitor-ID cookie. Managed automatically from Visitor data → Request log — edit it there, not here.

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Whether conversions and ad attribution are being recorded. Managed automatically from Visitor data → Conversions — edit it there, not here.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Sites visitors continue to (a booking site), for cross-domain ad attribution. Managed automatically from Visitor data → Conversions — edit it there, not here.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Public (referrer-restricted) Maps JavaScript key — the Service Area Map loads Google Maps with it. Managed automatically from Connections → Google Maps — edit it there, not here.

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Master switch for the site’s scroll and entrance motion (section reveals, count-ups, marquees, the hero). When off, no animation code is loaded and every section appears in its final, static state. Visitors whose device requests reduced motion always get the static experience regardless of this setting.

DesignLayer | null

Sometimes sent: undefined when the site leaves it out, and it can be null. A DesignLayer. Site-wide CSS for every section of a type and for shared elements (buttons, the header, the footer…). Type into the slot of the part you want to style; a section’s own CSS tab wins over this.

Show DesignLayer

Readonly<Record<string, string>>

Sometimes sent: undefined when the site leaves it out. The CSS typed into each part slot, by slot name.

string

Sometimes sent: undefined when the site leaves it out. The compiled CSS (read only: rebuilt from slots).

string

Sometimes sent: undefined when the site leaves it out. The site’s check mark for css (read only).

HeaderStyle | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Floating rests transparent over the hero and morphs to glass on scroll; Glass is frosted from the top; Solid is an opaque bar (uses the bar background color). One of floating, glass, solid; a newer site may send others, so keep a fallback.

HeaderWidth | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Island floats as a contained pill; Full width spans edge-to-edge (squared corners, content still centered). Full width ignores the corner radius below. One of island, full; a newer site may send others, so keep a fallback.

HeaderBarRadius | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Applies to the Island bar (Full width is always squared). One of pill, rounded, slight, square; a newer site may send others, so keep a fallback.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. The bar fill for Glass / Solid styles (and the glass tint when scrolled). Leave empty to use the raised surface color.

string | null

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. A hairline outline around the bar (shown when glass / solid / scrolled).

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. A soft drop shadow under the bar (when glass / solid / scrolled).

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. The bar slides away when scrolling down and returns when scrolling up.

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. The floating bar stays transparent at the top and becomes a glass pill once the page scrolls. Turn off to keep it transparent.

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Keeps the whole navbar (bar, logo, wordmark, links, dropdown, button and mobile menu) in its dark-theme look even when a visitor switches to the light theme, e.g. a header that always sits over a dark hero photo. While on, the light-theme header colors and the light-theme logo are not used. Off follows the site theme.

HeaderNavBreakpoint | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Below this width the links collapse into the mobile menu (hamburger). Raise it if you have many or long links. One of md, lg, xl; a newer site may send others, so keep a fallback.

HeaderLogoHeight | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Logo height. One of small, medium, large; a newer site may send others, so keep a fallback.

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. A subtle tilt + scale when the cursor is over the logo lockup.

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. The business name in type beside the logo. Turn off when the logo already includes the name.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Optional override of the text wordmark. Leave empty to use the business name.

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Render the first word large and the rest as a small tracked-out caption beneath it. Off renders the whole wordmark on one line.

string | null

HeaderNameWeight | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Weight. One of normal, medium, semibold, bold, extrabold; a newer site may send others, so keep a fallback.

HeaderNameSize | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Size. One of small, normal, large; a newer site may send others, so keep a fallback.

string | null

HeaderSublineWeight | null

readonly GlobalHeaderNavItem[] | null

Sometimes sent: undefined when the site leaves it out, and it can be null. A list of GlobalHeaderNavItem. Header navigation.

Show GlobalHeaderNavItem

string

Always sent. Label.

string

Always sent. URL.

string

Sometimes sent: undefined when the site leaves it out. The row’s id, unique in its array.

Placement | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Desktop only — every link is listed in the mobile menu. One of visible, more; a newer site may send others, so keep a fallback.

Readonly<Record<string, unknown>>

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Label for the overflow dropdown that holds links placed in “More”.

string | null

HeaderNavLinkWeight | null

HeaderNavLinkSize | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Size. One of small, normal, large; a newer site may send others, so keep a fallback.

HeaderNavIndicator | null

Sometimes sent: undefined when the site leaves it out, and it can be null. How the hovered / active link is marked. One of sweep, grow, pill, none; a newer site may send others, so keep a fallback.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Optional. Leave empty to use the site accent color.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Color + indicator for the current page’s link. Leave empty to use the secondary (mint) color.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. The visible button text. Leave empty to hide the button.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Where the button goes — a path (/blog) or full URL.

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Opens the link in a new browser tab (adds rel=“noopener noreferrer”).

HeaderCtaVariant | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Solid fills with the color; Outline / Soft / Text link use it for the border + text. One of solid, outline, soft, link; a newer site may send others, so keep a fallback.

HeaderCtaSize | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Button size. One of small, normal, large; a newer site may send others, so keep a fallback.

HeaderCtaRadius | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Corner radius. One of pill, rounded, slight, square; a newer site may send others, so keep a fallback.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Solid fill, or the border + text for the other styles. Defaults to the brand accent; CLEAR it for a transparent, outline-only button.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. The text/icon color. Clear it to derive from the button color (readable on solid fills).

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Optional. Drives the hover treatment. Leave empty to derive it from the button color.

string | null

HeaderCtaStyle | null

Sometimes sent: undefined when the site leaves it out, and it can be null. The hover treatment: a soft shadow, a colored offset shadow, a glow, a fill sweep, or a thicker border. One of none, single, dual, glow, sweep, thicken; a newer site may send others, so keep a fallback.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Optional. The offset-shadow or glow color on hover. Leave empty to use the site secondary color.

string | null

HeaderCtaAnimation | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Hover motion. One of lift, scale, lift-scale, none; a newer site may send others, so keep a fallback.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Any Font Awesome icon name, e.g. star, bolt, arrow-left-to-bracket (no “fa-” prefix). Browse at fontawesome.com/icons.

HeaderCtaIconFamily | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Icon family. One of classic-regular, duotone-regular, brands, jelly, jelly-duo, whiteboard; a newer site may send others, so keep a fallback.

HeaderCtaIconPosition | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Which side of the label the icon sits on (when an icon name is set). One of before, after; a newer site may send others, so keep a fallback.

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. The icon slides toward its side on hover (e.g. an arrow edges outward).

HeaderMobileSide | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Drawer side. One of right, left; a newer site may send others, so keep a fallback.

HeaderMobileWidth | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Drawer width. One of narrow, normal, wide; a newer site may send others, so keep a fallback.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Optional. Leave empty to use the site surface color.

string | null

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Show logo in drawer.

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Repeat the header button at the bottom of the mobile drawer.

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. A small animated hint shown when the menu links overflow.

string | null

HeaderMobileLinkWeight | null

HeaderMobileLinkSize | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Size. One of small, normal, large; a newer site may send others, so keep a fallback.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Optional. Leave empty to use the site accent color.

string | null

FooterBackgroundType | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Site default keeps the footer’s sunken surface; Solid color and Image override it. The site surface color is the fallback when a color is left empty. One of default, solid, image; a newer site may send others, so keep a fallback.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Used for a Solid background (and as the fallback behind an Image). Leave empty to use the site surface color.

string | null

ImageArea

Sometimes sent: undefined when the site leaves it out. An ImageArea. Widgets, top to bottom: send { "items": [ … ] }, one object per widget with its type. Writing it replaces the whole area. Its fields are listed under the first ImageArea above.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Scrim over the image to keep the footer legible. Leave empty to use the surface color.

string | null

number | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Overlay opacity (%). 0 to 100.

FooterPadding | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Vertical padding. One of tight, normal, roomy; a newer site may send others, so keep a fallback.

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. A hairline rule along the top edge of the footer.

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Show “Back to top” button.

readonly Readonly<Record<string, unknown>>[] | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Optional logo shown at the top of the company column, used on the dark theme. Leave both footer logos empty to use the site logo (Site settings → Brand); with no logo at all the business name leads. Upload to the Images library first. The related @apostrophecms/image documents, in order (empty when none). To set it, send a list of { "_id": "…" }, one per document (one at most); a document the site can’t find is left out. At most 1 items.

readonly Readonly<Record<string, unknown>>[] | null

FooterLogoHeight | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Logo height. One of small, medium, large; a newer site may send others, so keep a fallback.

FooterLogoAlign | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Aligns the logo within the company column (e.g. centered above the business name). One of left, center, right; a newer site may send others, so keep a fallback.

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. The business name as a heading at the top of the column. Turn off when the logo already carries the name.

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Show tagline.

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Show address, phone & email.

string | null

FooterNameWeight | null

FooterNameSize | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Size. One of small, normal, large; a newer site may send others, so keep a fallback.

string | null

FooterBrandWeight | null

FooterBrandSize | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Size. One of small, normal, large; a newer site may send others, so keep a fallback.

readonly GlobalFooterLinkGroupsItem[] | null

Sometimes sent: undefined when the site leaves it out, and it can be null. A list of GlobalFooterLinkGroupsItem. Each group becomes a column in the footer. Add a Legal group for Terms & Privacy, etc.

Show GlobalFooterLinkGroupsItem

string

Always sent. Group heading.

string

Sometimes sent: undefined when the site leaves it out. The row’s id, unique in its array.

readonly GlobalFooterLinkGroupsItemLinksItem[]

Sometimes sent: undefined when the site leaves it out. A list of GlobalFooterLinkGroupsItemLinksItem. Links.

Show GlobalFooterLinkGroupsItemLinksItem

string

Always sent. Label.

string

Always sent. URL.

string

Sometimes sent: undefined when the site leaves it out. The row’s id, unique in its array.

boolean

Sometimes sent: undefined when the site leaves it out. Opens in a new tab with an arrow indicator.

Readonly<Record<string, unknown>>

FooterLinkColumns | null

Sometimes sent: undefined when the site leaves it out, and it can be null. How many columns the link groups flow into. Auto fits to the available width; a fixed count packs shorter groups together (e.g. Legal stacked under Elsewhere). Groups are never split across columns. One of auto, 2, 3, 4; a newer site may send others, so keep a fallback.

string | null

FooterHeadingWeight | null

FooterHeadingSize | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Size. One of small, normal, large, xlarge; a newer site may send others, so keep a fallback.

string | null

FooterLinkWeight | null

FooterLinkSize | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Size. One of small, normal, large; a newer site may send others, so keep a fallback.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Optional. Leave empty to use the site accent color.

string | null

FooterLinkHoverEffect | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Hover effect. One of none, slide, underline; a newer site may send others, so keep a fallback.

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. A slow ribbon of phrases scrolling across the top of the footer. Any page can override this for itself in Page Settings → Footer.

readonly GlobalFooterMarqueeItem[] | null

Sometimes sent: undefined when the site leaves it out, and it can be null. A list of GlobalFooterMarqueeItem. Each phrase can carry its own icon; without one, a dot separates it from the next phrase.

Show GlobalFooterMarqueeItem

string

Always sent. Phrase.

string

Sometimes sent: undefined when the site leaves it out. The row’s id, unique in its array.

string

Sometimes sent: undefined when the site leaves it out. Any Font Awesome icon name, e.g. star, bolt, arrow-left-to-bracket (no “fa-” prefix). Browse at fontawesome.com/icons.

IconFamily | null

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Optional — leave empty to use the design’s own color rhythm.

IconAnimation | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Icon animation. One of none, fa-beat, fa-bounce, fa-fade, fa-beat-fade, fa-flip, fa-shake, fa-spin; a newer site may send others, so keep a fallback.

Readonly<Record<string, unknown>>

FooterMarqueeSpeed | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Marquee speed. One of slow, normal, fast; a newer site may send others, so keep a fallback.

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Adds a small, unobtrusive pause/play control so visitors can stop the auto-playing background motion (WCAG 2.2.2). Only appears when a moving background is set.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Optional. Leave empty for the muted default.

string | null

FooterMarqueeWeight | null

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. A giant outlined word along the bottom of the footer. Reveals/fills on hover.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Keep it to one short word — it renders at display size. Leave empty to use the business name.

FooterWordmarkSize | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Watermark size. One of display, large, medium; a newer site may send others, so keep a fallback.

FooterWordmarkAlign | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Watermark alignment. One of left, center, right; a newer site may send others, so keep a fallback.

FooterWordmarkFill | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Outlined letters that fill on hover one at a time, all at once, or always-solid (no ghost effect). One of letter, word, solid; a newer site may send others, so keep a fallback.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Optional. Overrides the wordmark fill + outline tint. Leave empty to track the theme’s text color.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Type {year} where this year goes (it updates itself every January) and {business} for the business name. Left empty, the site shows “© {year} {business}. All rights reserved.”

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Optional short line shown beside the copyright (e.g. a slogan or license number).

string | null

FooterCopyrightWeight | null

FooterCopyrightSize | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Size. One of small, normal, large; a newer site may send others, so keep a fallback.

Sometimes sent: undefined when the site leaves it out, and it can be null. Render the site’s social profiles (configured in the “Social Links” tab) in the footer.

Sometimes sent: undefined when the site leaves it out, and it can be null. Optional small heading above the icons (e.g. “Follow us”). Leave empty for none.

Sometimes sent: undefined when the site leaves it out, and it can be null. In the company column (under the contact details) or as its own centered row above the copyright bar. One of brand, bar; a newer site may send others, so keep a fallback.

Sometimes sent: undefined when the site leaves it out, and it can be null. A hairline rule above the dedicated social row, for a touch of separation from the watermark.

Sometimes sent: undefined when the site leaves it out, and it can be null. Icon style. One of bare, outline, solid; a newer site may send others, so keep a fallback.

Sometimes sent: undefined when the site leaves it out, and it can be null. Icon size. One of small, normal, large, xlarge; a newer site may send others, so keep a fallback.

Sometimes sent: undefined when the site leaves it out, and it can be null. Gap between the icons. One of tight, normal, loose; a newer site may send others, so keep a fallback.

Sometimes sent: undefined when the site leaves it out, and it can be null. Optional. Leave empty to match the footer’s other group headings (Footer: Links tab).

Sometimes sent: undefined when the site leaves it out, and it can be null. Resting icon color. Leave empty for the muted default.

Sometimes sent: undefined when the site leaves it out, and it can be null. Hover to each platform’s own brand color, or to the site accent (or a chosen hover color). One of brand, accent; a newer site may send others, so keep a fallback.

Sometimes sent: undefined when the site leaves it out, and it can be null. Used when “Hover color” is Accent / custom. Leave empty for the site accent.

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. OFF by default. While off, the server rejects every file submitted through a public form, regardless of the form’s fields. Turn on only after setting the limits below — anonymous file uploads are a deliberate, security-sensitive choice.

number | null

Sometimes sent: undefined when the site leaves it out, and it can be null. How many files one submission may include (hard ceiling 8). 1 to 8.

number | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Largest single file accepted, in megabytes (hard ceiling 10 MB). 1 to 10.

readonly FormUploadAllowedTypes[] | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Only these categories are accepted. Each file’s actual contents are verified by signature (magic bytes), not just its extension, so a renamed file is rejected. SVG and other script-capable formats can never be enabled here. Each one of image, pdf, office, text.

Sometimes sent: undefined when the site leaves it out, and it can be null. The draft’s preview share key, while its share link is on: the link is the draft’s _url with aposShareKey and aposShareId (the draft’s _id) in its query. Absent otherwise, and on published documents.

Readonly<Record<string, unknown>>

number

Always sent. Pages in the whole list (0 when it is empty).

number

Always sent. This page, from 1.

Errors

Nothing to catch: the SDK retries what is safe, and throws the rest as the classes below; catch only what you want to react to (see Errors and testing).

401

The API key is missing or refused (malformed, revoked, expired), or a signature its signing mode needs is missing or stale.Retried first: No. Read: siteMessage, errorName, data.

404

Nothing matches, or the caller may not see it.Retried first: No. Read: siteMessage, errorName, data.

5xx

The site failed (or something in front of it did). Its logs say why.Retried first: A 502, 503 or 504: yes, after 0.5 s then 1 s. A 500: no. Read: siteMessage, errorName, data.

no answer

No answer: DNS, a refused connection, TLS, or the timeout (15 s per attempt by default).Retried first: Yes, after 0.5 s then 1 s. Read: reason, neverConnected.

not sent

The client refused to send it (e.g. a path segment of ..); the site never saw it.Retried first: No. Read: reason (what to change).

any other

Any other status, or a success whose JSON doesn’t match this SDK version’s types (update the SDK).Retried first: No. Read: reason, status.

setup

sites.forSite('acme') named a slug your sites (createSiteClients()) don’t have.Retried first: No: nothing was sent. Read: message, slug.

setup

The client’s settings are wrong: no FETCHSKI_ATTRACT_URL (or baseUrl), or a malformed API key.Retried first: No: nothing was sent. Read: message (what to fix).

Behavior

Access: an API key with global:read (or a master above it: global:all, admin:all) reads the published documents; drafts (aposMode=draft) need global:write (or a master above it). A signed-in person may call it as far as their own permissions allow; anyone else gets 404.
Rate limit: the key’s own reads-per-minute limit, set when the key is created (default 600); over it, 429 with Retry-After. The client waits and retries for you; you see RateLimited only if that runs out.
Retries: a read is safe to repeat: the client retries it on no answer, a 502/503/504 and a 429.
Timeout: 15 s per attempt by default; raise timeout (milliseconds) on the client for longer.
Paging: one page per call. To walk them all, use listGlobalContentAll() (see More examples): it asks for the next page as you iterate, and stops after page pages.

More examples

listGlobalContentAll() takes listGlobalContent()’s arguments except page. listGlobalContentPick() takes the same arguments except page, after the fields to answer: each row is the document’s id and those fields.

import { createSiteClient } from '@fetchski/attract-cms-sdk';

const site = createSiteClient();
for await (const globalContent of site.globalContent().listGlobalContentAll()) {
  console.log(globalContent); // the next page is fetched as you iterate
}

import { createSiteClient } from '@fetchski/attract-cms-sdk';

const site = createSiteClient();
const rows = await site.globalContent().listGlobalContentPick(['title', 'slug']); // [{ id, title, slug }, …]: every global document, across every page

Test it

It calls the function above with a fake client: the fake answers every call with a valid example, so nothing leaves your machine and no settings or key are needed. Run it with node --test.

tests/globalContent-listGlobalContent.test.ts

import { test } from 'node:test';
import { fakeSite } from '@fetchski/attract-cms-sdk/testing';
import { listGlobalContent } from '../src/attract/list-global-content.ts';

test('globalContent.listGlobalContent', async () => {
  const site = fakeSite();
  await listGlobalContent(site);
  site.assertCalled('globalContent.listGlobalContent');
});

Answer with your own values: fake globalContent.listGlobalContent with a sequence() of pages, each factories.GlobalList({...}), and walk listGlobalContentAll().

tests/globalContent-listGlobalContent-answer.test.ts

import assert from 'node:assert/strict';
import { test } from 'node:test';
import { factories, fakeSite, sequence } from '@fetchski/attract-cms-sdk/testing';

test('globalContent.listGlobalContent answers your values', async () => {
  const site = fakeSite({
    'globalContent.listGlobalContent': sequence(
      factories.GlobalList({ currentPage: 1, pages: 2 }),
      factories.GlobalList({ currentPage: 2, pages: 2 })
    )
  });
  const walked: unknown[] = [];
  for await (const globalContent of site.globalContent().listGlobalContentAll()) {
    walked.push(globalContent);
  }
  assert.equal(walked.length, 2);
});

To fake listGlobalContentAll(), answer globalContent.listGlobalContent (the walk calls it page by page): a sequence() of answers for several pages.

Create a global document

site.globalContent().createGlobal()

Archive global documents

site.globalContent().archiveGlobals()

Copy global documents to another locale

site.globalContent().localizeGlobals()

Publish global documents

site.globalContent().publishGlobals()

Restore global documents

site.globalContent().restoreGlobals()

Get a global document

site.globalContent().getGlobal()

GET /@apostrophecms/global

The endpoint this calls, in the API reference: the HTTP request and answer, and every rule the site checks.

import { createSiteClient } from '@fetchski/attract-cms-sdk';

const site = createSiteClient();
const globalList = await site.globalContent().listGlobalContent();

{
  "results": [
    {
      "_id": "global",
      "slug": "global",
      "type": "@apostrophecms/global",
      "cookiePolicyVersion": "1",
      "cookieMessage": "This website uses cookies to supplement a balanced diet and provide a much deserved reward to the senses after consuming bland but nutritious meals. Accepting our cookies is optional but recommended, as they are delicious.",
      "cookieAcceptLabel": "Accept all",
      "cookieRejectLabel": "Reject all",
      "cookiePrefsTitle": "Cookie preferences",
      "createdAt": "2026-10-24T09:30:00.000Z",
      "updatedAt": "2026-10-24T09:30:00.000Z"
    }
  ],
  "pages": 1,
  "currentPage": 1
}

Get started

Using the SDK

Going further

Pages & Site

Content

Media

Forms

Ads & Conversions

Analytics

In your app

Behavior

More examples

Test it

Create a global document

Archive global documents

Copy global documents to another locale

Publish global documents

Restore global documents

Get a global document

GET /@apostrophecms/global

In your app

Behavior

More examples

Test it

Related

Create a global document

Archive global documents

Copy global documents to another locale

Publish global documents

Restore global documents

Get a global document

GET /@apostrophecms/global