Developer Docs

Install AI-citable FAQs in one line of code. SDKs, a REST API, and an MCP server.

Getting Started

Create a Claricard account and generate FAQs from a URL in the dashboard.
Share (embed) the FAQ to get its public slug.
Pull the slug with any SDK below. Reading needs no API key.

terminal

npm install @claricard/react

@claricard/react

One component renders the FAQ UI and FAQPage JSON-LD schema together — on your domain, no iframes.

app/page.tsx

import { FAQ } from '@claricard/react'

export default function Page() {
  return <FAQ slug="your-site" />
}

Theming & translation

<FAQ
  slug="your-site"
  lang="ja"                       // en, ko, ja, zh, es, fr, de
  theme={{ accentColor: '#000', questionSize: 18 }}
  showTitle={false}
/>

Headless — useFAQ()

Fetch the data and render any UI you want. Inject schema with <FAQSchema />.

import { useFAQ, FAQSchema } from '@claricard/react'

function MyFAQ() {
  const { data, isLoading } = useFAQ('your-site')
  if (isLoading || !data) return null

  return (
    <>
      <FAQSchema faq={data} />
      {data.items.map((item) => (
        <MyItem key={item.position} q={item.question} a={item.answer} />
      ))}
    </>
  )
}

@claricard/js

Framework-free core client. Works in Node 18+, browsers, and edge runtimes. Great for Next.js server components.

app/page.tsx (Server Component)

import { getFAQ, toJsonLdString } from '@claricard/js'

export default async function Page() {
  const faq = await getFAQ('your-site')

  return (
    <>
      <script
        type="application/ld+json"
        dangerouslySetInnerHTML={{ __html: toJsonLdString(faq) }}
      />
      {faq.items.map((item) => (
        <details key={item.position}>
          <summary>{item.question}</summary>
          <p>{item.answer}</p>
        </details>
      ))}
    </>
  )
}

REST API

Public read endpoint. No auth, CORS enabled, cached for 1 hour.

GET

https://app.claricard.com/api/v1/faq/{slug}?lang=ja

200 response

{
  "slug": "your-site",
  "title": "Your Site FAQ",
  "websiteName": "Your Site",
  "lang": "ja",
  "items": [
    { "position": 0, "question": "...", "answer": "..." }
  ],
  "cta": null
}

Publish — save FAQs & get a slug

Authenticated with your API key (X-Plugin-Key header). Saves the items and returns a ready-to-use public slug.

POST

curl -X POST https://app.claricard.com/api/v1/faq \
  -H "Content-Type: application/json" \
  -H "X-Plugin-Key: cc_live_..." \
  -d '{
    "websiteUrl": "https://yoursite.com",
    "websiteName": "Your Site",
    "items": [
      { "question": "...", "answer": "..." }
    ]
  }'

201 response

{
  "slug": "a1b2c3d4",
  "faqUrl": "https://app.claricard.com/faq/a1b2c3d4",
  "install": {
    "npm": "npm install @claricard/react",
    "component": "<FAQ slug=\"a1b2c3d4\" />"
  }
}

MCP Server

Generate and wire up FAQs from Claude Code, Cursor, and other MCP clients with a single prompt.

Claude Code

claude mcp add claricard -e CLARICARD_API_KEY=cc_live_... -- npx -y @claricard/mcp

Cursor · mcp.json

{
  "mcpServers": {
    "claricard": {
      "command": "npx",
      "args": ["-y", "@claricard/mcp"],
      "env": { "CLARICARD_API_KEY": "cc_live_..." }
    }
  }
}

Tool	Auth	Description
get_faq	—	Fetch a published FAQ by slug
get_faq_jsonld	—	FAQPage JSON-LD for a FAQ
generate_faq	API key	Generate new FAQs for a website
publish_faq	API key	Save FAQs & get a public slug

API Keys

Reading FAQs needs no key. Write operations (like FAQ generation) require a cc_live_ key. Create one in the dashboard under Developer → API Keys & Integrations, then pass it via the X-Plugin-Key header or the CLARICARD_API_KEY env var. Keys are shown once at creation — never hardcode them.