FAQ spaces

An FAQ space is the questions you answer over and over, answered once. Each question is its own page, so it can be linked and searched. The reader opens on a landing that groups the questions, and every answer is marked up for search engines as an FAQ. This guide covers the content model, the looks and how to mix them, every theme.faq key, the pages around the landing (section pages, tag pages, feeds, the markdown twin, the help widget), one question's own overrides, the outlets and the settings.

The content model

An FAQ space holds pages, one per question, exactly like a documentation space. There is nothing else to learn: a question is a page, the page's title is the question, and the page's body is the answer.

The fields on each question:

How questions are grouped

Two rules, in this order:

1. If any published question has a topic, the page is grouped by topic. One heading per distinct topic, in the order the topics first appear in reading order (not alphabetically — the order you arranged your questions in is the only ordering you expressed). Questions with no topic are kept, in one unheaded group at the end.

2. If no question has a topic, the page is grouped by the space's collections, and a collection's name is its heading. The auto-created default collection has no heading.

Each section in GET /public/orgs/{org}/spaces/{space}/faq says which it is:

{ "sections": [ { "name": "Billing", "kind": "topic", "id": "", "questions": [ … ] } ] }

kind: "collection" sections carry the collection's id; kind: "topic" sections carry no id, because the heading is a field value shared by the questions beneath it rather than something that can be renamed in place.

Nested sections

A collection can sit inside another, up to six deep, for a help desk whose categories hold sections. Set parentId on POST …/collections or PATCH …/collections/{collectionId}; a parent in another space, a cycle or a seventh level is refused with a 422. Deleting a parent moves its children up rather than deleting them. In the studio it is the collection settings' Inside picker.

The payload lists sections depth-first with parentId and depth; a parent with no questions of its own is kept when it heads sub-sections. On the landing the sub-sections' headings step down and indent; a section page shows the trail through its parents (visibly and in BreadcrumbList) and lists its sub-sections; the markdown twin's headings follow the depth.

How to fill it by API

# 1. The space
POST /orgs/{org}/spaces
  { "name": "FAQ", "slug": "faq", "type": "FAQ", "visibility": "PUBLIC" }

# 2. A question (collection id from GET /orgs/{org}/spaces/{space}/collections)
POST /orgs/{org}/spaces/{space}/collections/{collection}/pages
  { "title": "Do you offer refunds?", "slug": "refunds" }

# 3. The answer
PUT /orgs/{org}/spaces/{space}/pages/{page}/content
  { "title": "Do you offer refunds?", "content": { … block doc … } }

# 4. File it under a topic, and pin it
PATCH /orgs/{org}/spaces/{space}/pages/{page}/metadata
  { "fields": { "topic": "Billing", "pinned": true } }

# 5. Publish — an unpublished question is not on the page
POST /orgs/{org}/spaces/{space}/pages/{page}/publish

docs/import works here too: one markdown document per question.

Importing from a help desk

POST /orgs/{orgId}/spaces/{spaceId}/docs/import/helpdesk brings in a Zendesk, Intercom or Help Scout help centre, either from a pasted export or pulled live with your own API token (used for that one request, never stored). Categories and sections become nested collections, drafts are skipped, and a re-run updates pages in place. Try it with dryRun first. Details in Importers.

Presets

The preset is the landing's arrangement, set with PUT /orgs/{orgId}/spaces/{spaceId}/preset or in the studio's Look fold.

Looks are patches

theme.faq.look picks a starting point. A look is a handful of independent keys laid under your own (theme → space → question), so any key you set still wins and any key a look sets can be set alone under another look. Set looks and keys with PATCH /orgs/{orgId}/spaces/{spaceId}/theme; like every theme object, a misspelt key is a 422 that names it.

The default layer:

• item: style: row and icon: chevron (unless you gave every collapsible a look in theme.components.expandable, which then reaches the FAQ too), feedback: open-only, followUp: true, copyLink: true;

• search: a centred hero with a large box, the ⌘K shortcut, highlight and count;

• contact: all four cards (contact, community, docs, status);

• categories: show: auto, layout: grid, with icon, description and count;

• featured: show: auto, from: featured, layout: rows;

• audience: chip: true, filter: auto;

• follow.sections: true;

• questionPage.related: auto.

item.feedback: off also turns off "Was this page helpful?" on each question's own page, unless you set theme.docs.feedback yourself.

Combinations no look gives you

The pricing accordion with a search box back above it:

curl -X PATCH "https://forumulate.com/api/orgs/$ORG/spaces/$SPACE/theme" \
  -H "Authorization: Bearer $FORUMULATE_TOKEN" -H 'content-type: application/json' \
  -d '{ "faq": { "look": "pricing", "search": { "placement": "inline", "size": "md" } } }'

The support help centre, but ordered by your hand and without the public helpfulness rate:

{ "faq": { "look": "support", "sort": "manual", "item": { "helpfulStat": false } } }

The minimal list in cards, two columns, grouped under sticky headings with counts:

{
  "faq": {
    "look": "minimal",
    "list": { "layout": "grid", "columns": 2, "group": { "by": "field", "field": "topic", "sticky": true, "counts": true } },
    "item": { "style": "card" }
  }
}

The landing keys

Top level

list

The questions' arrangement, drawn by the FAQ's own list, so every item, search, audience, follow and jump key composes with every arrangement.

item — one question

search

The FAQ's search reports what readers looked for, and how many questions matched, to the same content-gap report docs search feeds.

Help-centre bands

Phone and print

The front-door switches on PUT …/preset under frontDoor turn whole bands off: showSearch, showContact, showCategoryCards, showFeatured and showRss (all on), plus badgeStyle.

Section pages, tag pages and the question page

A section's own page: /c/<slug>

Every section, a topic as well as a collection, has its own page, with FAQPage structured data, a search box scoped to it, the FAQ's own list and item look, its introduction, its sibling sections and the contact door. On a topic-grouped FAQ, the hidden default collection has no page (404); the topics do. theme.faq.sectionPage:

Tag pages: /tags/<tag>

A question links each of its tags here. A tag page is the section page's body over the questions carrying that tag, so it wears the same list, item look and door, and its FAQPage covers exactly what it shows.

One question's own page

A question's page is a documentation page at the FAQ's prefix, so it takes the docs page keys too. theme.faq.questionPage adds under the answer:

One question's overrides

A question carries its own look in its page metadata: CSS, token keys, a share image, og title and description, JSON-LD, and the theme.faq and theme.docs namespaces, which its own page reads over the space's (questionPage, the helpfulness line, the docs page keys). Any other type's namespace is refused with a 422 naming it. A page's theme is replaced whole on each write, and null clears it.

curl -X PATCH "https://forumulate.com/api/orgs/$ORG/spaces/$SPACE/pages/$PAGE/metadata" \
  -H "Authorization: Bearer $FORUMULATE_TOKEN" -H 'content-type: application/json' \
  -d '{ "theme": { "faq": { "questionPage": { "siblings": true, "follow": true } } } }'

In the studio it is Page look & sharing on the question. The general rules are in Theme your site → Per-page customization.

Feeds, markdown and the help widget

The help widget puts a help launcher in your own product. It opens on the questions suggested for the page the reader is on (a question whose tag or topic names a segment of the host page's path, or the words in data-context), filters as the reader types, opens an answer in place, and sends "Contact us" where the FAQ's own door goes:

<script src="https://forumulate.com/api/embed/faq.js" data-org="ORG_ID" data-space="SPACE_ID" async></script>

Options are data-* attributes: data-mode (launcher, the default, or inline), data-position (right or left), data-context="billing,invoices", data-accent, data-radius, data-width, data-font, data-title, data-locale and data-theme (light, dark, auto). window.Forumulate.faq.open(), .close() and .toggle() drive it from your code. Gated questions never reach it.

Following

A reader can follow the whole FAQ, one section or one question (POST /public/orgs/{orgId}/spaces/{spaceId}/faq/follow with section, a section slug, or question, a page id, or neither) and is emailed when a question there is added or materially changed. A signed-in reader with a verified address follows at once; anyone else gives an address and confirms it from the inbox. Every mail carries a one-click unsubscribe.

The contact door

The FAQ reader ends with "Didn't find an answer? Contact us". You choose where that goes, and by default there is no link at all.

GET  /orgs/{org}/spaces/{space}/faq-settings   → { "contactSpaceId": null }
PUT  /orgs/{org}/spaces/{space}/faq-settings
  { "contactSpaceId": "<a CONTACT space in this org>" }   # null removes the link

The target must be a live, PUBLIC CONTACT space in the same organization; anything else is refused with 422. The reader resolves it to the space's real public address — your own domain, or a path of your site, or our reader — which is what contactUrl carries:

{ "contactUrl": "https://acme.com/contact", "contactPath": "https://acme.com/contact" }

contactPath is the same value under its old name and is deprecated; read contactUrl. If the chosen space is later deleted or made private, the link disappears rather than pointing at a 404.

What readers see

• Every published question with its answer (minus hideOnLanding ones) at /faq/{org}/{space} (or your own address), in the arrangement, look and order above.

• FAQPage structured data built from the same text, so a search engine can lift an answer straight into a result. A page with no questions emits none.

• A "Was this helpful?" control per question, which reports to the same page-feedback inbox the docs reader uses.

Front page

An FAQ space's front page is a composed document. Until you edit it, it is generated from the FAQ's own bands, in this order: title, search, intro, categories, featured, questions, contact (the two-column preset puts title, intro and contact in its left rail and search and questions beside it). Each is a {"type": "spaceBand", "attrs": {"band": "…"}} you can move or remove, and each draws what the FAQ's settings and theme.faq say:

An FAQ feed (spaceFeed on an FAQ space) sorts by latest, helpful or views, filters by section and featured, and its cards show title, section, excerpt and category.

The contact band: "Still need help?"

theme.faq.contact decides the cards (the band draws nothing until that key is set, by a look or by you, and the front door's showContact: false hides it). Each switch is on unless set to false; the band hides when no card and no email is left to show:

Every card links to the space's real public address (your domain, a site path, or our reader). "Exactly one" is deliberate: with two forums we cannot know which one you mean, and a wrong link is worse than none. To point at a particular space anyway, drop the band and write the cards yourself.

Outlets

Theme components (Theme components) can be placed in:

A question's own page also takes the documentation page's outlets.

In the studio

• Look fold: the preset, the front-door switches, and FAQ design — the look and the keys an owner reaches for first (arrangement, order, width, the question, the search box, section heads, the audience filter, phone and print). Every key also opens by double-clicking its part on the page.

• Settings fold → Contact link: where "Contact us" goes.

• Settings fold → Network access: the IP allow-list (below).

• A collection's settings → Inside: nest it under another section.

• A question → Page look & sharing: its own overrides.

Restricting an FAQ to your network

settings.networkAccess.ipAllowList limits every public read of the FAQ (pages, feeds, markdown, JSON and the help widget) to a list of IP addresses and CIDR blocks — an internal IT help desk, say. Readers elsewhere see "Not available from this network"; an empty list means everyone. See Network allow-list.

Templates

Six official FAQ templates start a space with a look and sample questions: Meadow (an editorial help centre with a landscape hero), Lamplight (a gradient search hero and category cards), Helmsway (a restrained support site), Patchbay (contact first, then ruled rows), Pricefold (the pricing-page FAQ in two columns) and Lockstep (an internal IT help desk with nested sections, pinned and badged questions and the Updated chip).

What you need to set up

The FAQ needs no account or credential. These parts stay hidden until their data exists:

• The contact link and card — until you choose a public CONTACT space under Contact link, there is no link.

• The community, docs and status cards — each only when the organization has exactly one public space of that kind.

• Popular questions — until a question is marked featured (or, with from: helpful or views, until there are votes or views to rank by).

• The helpfulness rate — until an answer has helpfulStatMin votes.

• Category cards under show: auto — until there are three headed sections.

• Help-desk import — your own Zendesk, Intercom or Help Scout token, entered in the import panel for one run.

• Network access — open to everyone until you add an address.

Published. https://forumulate.com/guides/faq-spaces, in the guides space's "Building your site" collection. Re-import after editing — the page is not generated from this file.

In the API

Every operation below is also reachable from the other surfaces without a dedicated command. forumulate api <Operation> calls it from the CLI, the JavaScript SDK has a typed method for each one (the last column names it; the Python and Go clients are generated from the same spec), and an agent reaches the organization-scoped ones through the MCP call_api tool. Where a CLI command or MCP tool exists too, the last column names it. Operation names link to the API reference.

Public faq

Public Faq Follow

Revision

Space Settings faq settings