개발자 문서

AI 검색에 인용되는 FAQ를 코드 한 줄로 설치하세요. SDK, REST API, MCP 서버를 지원합니다.

시작하기

클래리카드 계정을 만들고 대시보드에서 URL로 FAQ를 생성하세요.
FAQ를 공유(임베드)하면 공개 slug가 발급됩니다.
아래 SDK 중 하나로 slug를 불러오세요. 읽기에는 API 키가 필요 없습니다.

terminal

npm install @claricard/react

@claricard/react

컴포넌트 하나로 FAQ UI와 FAQPage JSON-LD 스키마가 함께 렌더링됩니다 — iframe 없이, 당신의 도메인에서.

app/page.tsx

import { FAQ } from '@claricard/react'

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

테마 & 번역

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

Headless — useFAQ()

데이터만 가져와 원하는 UI로 렌더링하세요. 스키마는 <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

프레임워크 무관 코어 클라이언트. Node 18+, 브라우저, 엣지 런타임 어디서든 동작합니다. Next.js 서버 컴포넌트에 적합해요.

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

공개 읽기 엔드포인트입니다. 인증 불필요, CORS 허용, 1시간 캐싱.

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
}

발행 — FAQ 저장 + slug 발급

API 키(X-Plugin-Key 헤더)로 인증합니다. 항목을 저장하고 즉시 사용 가능한 공개 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 서버

Claude Code, Cursor 같은 AI 코딩 툴에서 프롬프트 한 줄로 FAQ를 생성하고 연결하세요.

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	설명
get_faq	—	발행된 FAQ를 slug로 조회
get_faq_jsonld	—	FAQPage JSON-LD 반환
generate_faq	API key	웹사이트용 FAQ 신규 생성
publish_faq	API key	FAQ 저장 + 공개 slug 발급

API 키

FAQ 읽기에는 키가 필요 없습니다. FAQ 생성 등 쓰기 작업에만 cc_live_ 키가 필요해요. 대시보드의 개발자 → API 키 & 연동에서 발급하고, X-Plugin-Key 헤더 또는 CLARICARD_API_KEY 환경변수로 전달하세요. 키는 발급 시 한 번만 표시되며, 코드에 하드코딩하지 마세요.