Skip to main content

FAQ API

Admin endpoints (JWT)​

Base path: /api/v1/dashboard/faq

CRUD​

  • GET /?entityType=product&entityId=123&locale=en — list FAQs for an entity
  • POST / — create
  • PATCH /:id — update
  • DELETE /:id — delete

Bulk​

  • POST /bulk — array of FAQ objects
  • POST /import/csv — CSV body (see FAQ editor)
  • GET /export/csv — export. No filters → all tenant FAQs. With ?entityType=…&entityId=… → filtered.
  • GET /template — sample JSON format

Generation​

  • POST /generate — LLM-generated FAQs for a given entity (draft status, pending approval)
  • POST /:id/approve — approve a generated draft
  • POST /:id/reject — reject

Public endpoint (API key)​

Used by the embed widget. Rate-limited 200 req / 5 min per key.

GET /api/v1/public/faq/render?entityType=product&entityId=123&pageUrl=https://shop.example.com/products/foo
X-API-Key: sk_live_...
Origin: https://shop.example.com

The Origin header must match the API key's allowedDomains whitelist.

Response:

{
  "data": {
    "entries": [{ "question": "...", "answer": "..." }],
    "jsonLd": { "@context": "https://schema.org", "@type": "FAQPage", ... },
    "scriptTag": "<script type=\"application/ld+json\">...</script>",
    "htmlBlock": "<div class=\"clione-faq\">...</div>",
    "entryCount": 5,
    "specificCount": 3,
    "globalCount": 2
  }
}

The response merges entity-specific FAQs with tenant global FAQs automatically (entity-specific first, globals after, each ordered by sortOrder).

Entity types​

product, variant, category, collection, brand, page, global.

FAQ in signal endpoints​

FAQ entries are automatically bundled into the .jsonld endpoints for ALL entity types. When an entity has approved, visible FAQ entries, the JSON-LD response becomes a @graph array combining the entity schema (Product, CollectionPage, CategoryPage, WebPage) with a FAQPage schema:

{
  "@context": "https://schema.org",
  "@graph": [
    { "@type": "Product", "name": "...", ... },
    { "@type": "FAQPage", "mainEntity": [...] }
  ]
}

This applies to:

  • GET /api/v1/{platform}/products/:id.jsonld
  • GET /api/v1/{platform}/collections/:id.jsonld (Shopify)
  • GET /api/v1/{platform}/categories/:id.jsonld (BigCommerce)
  • GET /api/v1/{platform}/pages/:id.jsonld

The embed widget (embed.js) also injects FAQ JSON-LD client-side as a standalone FAQPage block.