Skip to main content

FAQ API

Dashboard endpoints (JWT)​

Base path: /api/v1/dashboard/faq. Writes and GET /pending need the owner or admin role.

CRUD​

  • GET /?entityType=product&entityId=123&locale=en&storeId=... — list FAQs (limit default 200, max 1000; offset)
  • 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 FAQs of the organization. With ?entityType=…&entityId=… (and optional locale, storeId) → filtered.
  • GET /template — sample JSON format for imports. entityId is the platform's own id of the entity (for example the BigCommerce product id 112), not Clione's internal id.

Generation and review​

  • POST /generate — LLM-generated FAQs for an entity. They are created approved and visible, and charged against the enrichment quota
  • POST /:id/approve — approve a pending question submitted from the storefront (body: answer, optional reviewedBy)
  • POST /:id/reject — reject
  • GET /pending — questions submitted from the storefront, awaiting review

Overview​

  • GET /stats?storeId=… — counters: live questions and the entities they answer
  • GET /entities?storeId=…&entityType=… — entities that have at least one FAQ

FAQ library​

Base path: /api/v1/dashboard/faq-library. A library entry is one canonical answer, linked explicitly to the entities that should show it.

  • GET / — list library entries
  • POST / — create an entry
  • PATCH /:id — update
  • DELETE /:id — delete
  • GET /:id/links — the entities an entry is linked to
  • POST /:id/links — link the entry to an entity (entityType, entityId), or, with scope: "store", to every entity of one entityType in a store (needs entityType and storeId)
  • DELETE /:id/links — unlink
  • GET /export.csv, POST /import/csv, GET /template.csv — CSV round trip

Public endpoints (API key)​

Base path: /api/v1/public/faq. Used by the FAQ widget. Every call needs an API key with the products:read scope; the organization comes from the key, never from a header. Rate-limited to 200 requests per 5 minutes per key. The request must also pass the key's allowedDomains and browser checks — see Authentication.

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

Query parameters: entityType, entityId (required), locale, pageUrl, heading, storeId (optional — defaults to the key's store).

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,
    "libraryCount": 2,
    "tenantPlatformId": "..."
  }
}

entries merges the entity's own FAQs with the library entries linked to it, ordered by sortOrder. specificCount counts the entity's own, libraryCount the library ones. When the entity has no FAQs, the response is { "data": null, "message": "No FAQ entries found for this entity" }.

Other public endpoints:

  • POST /submit — a shopper submits a question (entityType, entityId, question, optional submittedBy). It is stored as pending and shows up in GET /api/v1/dashboard/faq/pending. Returns 201.
  • GET /ping — confirms the key is valid; returns tenantId, tenantPlatformId, scopes and serverTime.

Entity types​

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

FAQ in signal endpoints​

Approved, visible FAQ entries are part of the .jsonld endpoints for every entity type. When an entity has them, the @graph includes a FAQPage node next to the entity's own node:

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

This applies to:

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

On the storefront, the FAQPage JSON-LD travels in the server-side graph Clione publishes through the platform. The widget (embed.js) renders the visible FAQ accordion, and it does not add a second FAQPage when the page already carries one.