> ## Documentation Index
> Fetch the complete documentation index at: https://docs.factagora.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API 카탈로그

> Factagora Search API 6종을 워크플로우 중심으로 안내합니다

이 페이지는 6가지 Search API를 요청·응답·결과 해석 흐름까지 한 번에 보여줍니다. 전체 파라미터 명세는 [API Reference](/ko/api-reference/introduction)를 참고하세요.

<Info>
  모든 엔드포인트는 동일한 인증을 사용합니다: `Authorization: Bearer fag_your_api_key`. [Factagora 대시보드](https://factagora.com)에서 발급한 키로 `fag_your_api_key`를 교체하세요.
</Info>

## 1. Fact Search

**`GET /api/v1/fact-search`** · 1 크레딧 · 실시간 의미 기반 뉴스 검색.

키워드가 아닌 의미(Semantic) 기반으로 뉴스를 검색합니다. 게시 날짜, 출처 도메인, 관련도 점수가 함께 반환됩니다.

<CodeGroup>
  ```bash cURL theme={null}
  curl -G "https://api.factagora.com/api/v1/fact-search" \
    -H "Authorization: Bearer fag_your_api_key" \
    --data-urlencode "q=ECB 금리 결정" \
    --data-urlencode "limit=5" \
    --data-urlencode "timespan=7d"
  ```

  ```python Python theme={null}
  import requests

  resp = requests.get(
      "https://api.factagora.com/api/v1/fact-search",
      headers={"Authorization": "Bearer fag_your_api_key"},
      params={"q": "ECB 금리 결정", "limit": 5, "timespan": "7d"},
  )
  data = resp.json()
  ```

  ```typescript TypeScript theme={null}
  const params = new URLSearchParams({
    q: "ECB 금리 결정",
    limit: "5",
    timespan: "7d",
  });
  const resp = await fetch(
    `https://api.factagora.com/api/v1/fact-search?${params}`,
    { headers: { Authorization: "Bearer fag_your_api_key" } },
  );
  const data = await resp.json();
  ```
</CodeGroup>

### 응답

```json theme={null}
{
  "query": "ECB 금리 결정",
  "results": [
    {
      "title": "ECB raises rates by 25bp, signals pause",
      "url": "https://example.com/ecb-rate-hike",
      "publishedAt": "2024-06-15T08:00:00Z",
      "source": "reuters.com",
      "language": "english"
    }
  ],
  "meta": { "executionTimeMs": 412 }
}
```

<Info>
  **`timespan`으로 신선도를 유지하세요.** 최신순이 중요하다면 `sortBy=date`와 함께 사용해 가장 최근 기사를 우선 반환받을 수 있습니다.
</Info>

## 2. Fact Checker

**`POST /api/v1/fact-checker`** · 2 크레딧 · 주장에 대한 사실 검증.

주장을 보내면 **TRUE / FALSE / UNCERTAIN** 판정과 신뢰도 점수, Factagora 지식 베이스 기반의 근거 출처를 반환합니다.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.factagora.com/api/v1/fact-checker" \
    -H "Authorization: Bearer fag_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{"claim": "ECB는 2024년 6월에 금리를 인상했다."}'
  ```

  ```python Python theme={null}
  resp = requests.post(
      "https://api.factagora.com/api/v1/fact-checker",
      headers={"Authorization": "Bearer fag_your_api_key"},
      json={"claim": "ECB는 2024년 6월에 금리를 인상했다."},
  )
  result = resp.json()
  ```

  ```typescript TypeScript theme={null}
  const resp = await fetch("https://api.factagora.com/api/v1/fact-checker", {
    method: "POST",
    headers: {
      Authorization: "Bearer fag_your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      claim: "ECB는 2024년 6월에 금리를 인상했다.",
    }),
  });
  const result = await resp.json();
  ```
</CodeGroup>

### 응답

```json theme={null}
{
  "claim": "ECB는 2024년 6월에 금리를 인상했다.",
  "verdict": "TRUE",
  "confidence": 0.92,
  "summary": "다수의 검증된 출처가 ECB가 2024년 6월 6일 예금금리를 25bp 인상했음을 확인합니다.",
  "sources": [
    {
      "title": "ECB June 2024 monetary policy decision",
      "url": "https://factagora.com/claims/abc-123"
    }
  ]
}
```

<Warning>
  **`confidence < 0.5`는 판정에 관계없이 `UNCERTAIN`으로 다루세요.** 판정은 AI의 최선의 추정이고, 신뢰도는 증거가 그 판정을 얼마나 강하게 뒷받침하는지를 나타냅니다.
</Warning>

## 3. Evidence Hunter

**`POST /api/v1/evidence-finder`** · 2 크레딧 · 근거 탐색 및 출처 확장.

주장에 대해 다각도 근거를 반환합니다. 각 결과는 유형(`DATA`, `EXPERT`, `NEWS`, `FACT_CHECK`), 신뢰도 점수, 입장(찬성·반대·중립)이 함께 표기됩니다.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.factagora.com/api/v1/evidence-finder" \
    -H "Authorization: Bearer fag_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{"claim": "탄소 가격제는 산업 부문 배출량을 줄인다.", "limit": 5}'
  ```

  ```python Python theme={null}
  resp = requests.post(
      "https://api.factagora.com/api/v1/evidence-finder",
      headers={"Authorization": "Bearer fag_your_api_key"},
      json={"claim": "탄소 가격제는 산업 부문 배출량을 줄인다.", "limit": 5},
  )
  data = resp.json()
  ```

  ```typescript TypeScript theme={null}
  const resp = await fetch("https://api.factagora.com/api/v1/evidence-finder", {
    method: "POST",
    headers: {
      Authorization: "Bearer fag_your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      claim: "탄소 가격제는 산업 부문 배출량을 줄인다.",
      limit: 5,
    }),
  });
  const data = await resp.json();
  ```
</CodeGroup>

### 응답

```json theme={null}
{
  "claim": "탄소 가격제는 산업 부문 배출량을 줄인다.",
  "results": [
    {
      "summary": "OECD 연구에 따르면 탄소 가격제 도입 후 적용 부문 배출량이 5~15% 감소했습니다.",
      "source": "https://oecd.org/...",
      "type": "DATA",
      "credibility": 0.91,
      "stance": "supports"
    },
    {
      "summary": "산업 경제학자는 단기 배출 감소가 탄소 누출로 상쇄된다고 주장합니다.",
      "source": "https://example.com/...",
      "type": "EXPERT",
      "credibility": 0.74,
      "stance": "contradicts"
    }
  ]
}
```

<Info>
  **`stance`로 시각의 균형을 맞추세요.** 결과가 모두 `supports`라면 충분히 탐색되지 않았을 수 있습니다, limit를 늘리거나 주장을 좁혀 반대 근거를 함께 확인하세요.
</Info>

## 4. Deep Research

**`POST /api/v1/deep-research`** · 2 크레딧 · 다중 출처 리서치 자동화.

주제에 대해 검증된 주장·뉴스·시계열 이벤트를 통합하고, 섹션과 인용이 포함된 구조화된 리포트를 생성합니다.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.factagora.com/api/v1/deep-research" \
    -H "Authorization: Bearer fag_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{"query": "미국 관세가 글로벌 반도체 공급망에 미치는 영향"}'
  ```

  ```python Python theme={null}
  resp = requests.post(
      "https://api.factagora.com/api/v1/deep-research",
      headers={"Authorization": "Bearer fag_your_api_key"},
      json={"query": "미국 관세가 글로벌 반도체 공급망에 미치는 영향"},
  )
  report = resp.json()
  ```

  ```typescript TypeScript theme={null}
  const resp = await fetch("https://api.factagora.com/api/v1/deep-research", {
    method: "POST",
    headers: {
      Authorization: "Bearer fag_your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      query: "미국 관세가 글로벌 반도체 공급망에 미치는 영향",
    }),
  });
  const report = await resp.json();
  ```
</CodeGroup>

### 응답

```json theme={null}
{
  "query": "미국 관세가 글로벌 반도체 공급망에 미치는 영향",
  "summary": "첨단 칩에 대한 미국의 관세는 공급망 지역화를 가속화했으며, 대만·한국·ASEAN의 팹 투자에서 뚜렷한 변화가 관찰됩니다.",
  "sections": [
    { "title": "Background", "content": "..." },
    { "title": "Current State", "content": "..." },
    { "title": "Key Debates", "content": "..." },
    { "title": "Conclusion", "content": "..." }
  ],
  "timeseries": {
    "title": "주요 관세·정책 이벤트",
    "dataPoints": [
      { "date": "2022-10-07", "event": "미국, 중국향 첨단 칩 수출 통제 발표" }
    ]
  },
  "sources": [
    { "title": "...", "url": "..." }
  ]
}
```

<Info>
  **요약(summary)을 최종 답변이 아닌 초안으로 다루세요.** Deep Research는 다수 출처를 종합하지만, 중요한 의사결정에서는 반드시 인용된 출처를 직접 확인해야 합니다.
</Info>

## 5. Timeseries

**`POST /api/v1/timeseries`** · 3 크레딧 · 시간 흐름 기반 정보 추출.

URL 또는 업로드한 문서(PDF·Markdown)에서 시계열 이벤트를 추출합니다.

<CodeGroup>
  ```bash cURL (URL) theme={null}
  curl -X POST "https://api.factagora.com/api/v1/timeseries" \
    -H "Authorization: Bearer fag_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://example.com/ai-act-history"}'
  ```

  ```bash cURL (파일 업로드) theme={null}
  curl -X POST "https://api.factagora.com/api/v1/timeseries/file" \
    -H "Authorization: Bearer fag_your_api_key" \
    -F "file=@report.pdf"
  ```

  ```python Python theme={null}
  resp = requests.post(
      "https://api.factagora.com/api/v1/timeseries",
      headers={"Authorization": "Bearer fag_your_api_key"},
      json={"url": "https://example.com/ai-act-history"},
  )
  data = resp.json()
  ```
</CodeGroup>

### 응답

```json theme={null}
{
  "title": "EU AI Act timeline",
  "dataPoints": [
    { "date": "2021-04-21", "event": "European Commission proposes AI Act" },
    { "date": "2023-12-08", "event": "Provisional political agreement reached" },
    { "date": "2024-03-13", "event": "European Parliament adopts the AI Act" }
  ]
}
```

<Info>
  **URL로 접근할 수 없는 PDF·Markdown은 `/timeseries/file`을 사용하세요**: 사내 보고서·백서 등을 업로드해 처리할 수 있습니다.
</Info>

## 6. Causality Graph

**`POST /api/v1/causality-graph`** · 3 크레딧 · 인과관계 분석.

URL 또는 문서에서 원인-결과를 분석해 방향성 그래프로 반환합니다. 노드는 개념·이벤트, 엣지는 인과 관계입니다.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.factagora.com/api/v1/causality-graph" \
    -H "Authorization: Bearer fag_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://example.com/economic-analysis"}'
  ```

  ```python Python theme={null}
  resp = requests.post(
      "https://api.factagora.com/api/v1/causality-graph",
      headers={"Authorization": "Bearer fag_your_api_key"},
      json={"url": "https://example.com/economic-analysis"},
  )
  graph = resp.json()
  ```

  ```typescript TypeScript theme={null}
  const resp = await fetch("https://api.factagora.com/api/v1/causality-graph", {
    method: "POST",
    headers: {
      Authorization: "Bearer fag_your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ url: "https://example.com/economic-analysis" }),
  });
  const graph = await resp.json();
  ```
</CodeGroup>

### 응답

```json theme={null}
{
  "nodes": [
    { "id": "n1", "label": "금리 인상" },
    { "id": "n2", "label": "주택담보대출 수요 감소" },
    { "id": "n3", "label": "주택 가격 하락" }
  ],
  "edges": [
    { "from": "n1", "to": "n2", "relation": "causes" },
    { "from": "n2", "to": "n3", "relation": "causes" }
  ]
}
```

<Info>
  **Timeseries와 함께 쓰면 전체 그림이 완성됩니다.** Timeseries는 *언제*를, Causality Graph는 *왜*를 답해, 둘을 결합하면 사건의 흐름을 처음부터 끝까지 재구성할 수 있습니다.
</Info>

## 요약

| API             | 엔드포인트                   | 용도              | 크레딧 |
| --------------- | ----------------------- | --------------- | --- |
| Fact Search     | `GET /fact-search`      | 실시간 의미 기반 뉴스 검색 | 1   |
| Fact Checker    | `POST /fact-checker`    | 주장 검증 + 판정/신뢰도  | 2   |
| Evidence Hunter | `POST /evidence-finder` | 다각도 신뢰도 기반 근거   | 2   |
| Deep Research   | `POST /deep-research`   | 다중 출처 종합 리포트    | 2   |
| Timeseries      | `POST /timeseries`      | 시계열 이벤트 추출      | 3   |
| Causality Graph | `POST /causality-graph` | 인과관계 그래프        | 3   |