> ## 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.

# Embed & Detect

> 콘텐츠 fingerprinting과 탐지를 위한 단계별 가이드

## 1. 워터마크 삽입

`/fingerprint/embed`에 콘텐츠를 보내 TKG를 추출하고 워터마크를 삽입합니다.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.factagora.com/api/v1/fingerprint/embed" \
    -H "Authorization: Bearer fag_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "content": "The European Central Bank raised interest rates by 25 basis points on Thursday, citing persistent core inflation in the eurozone. Analysts at Goldman Sachs expect one more hike before a pause in Q4.",
      "content_type": "news",
      "metadata": {
        "author_id": "editor_jane",
        "published_at": "2024-06-15T08:00:00Z",
        "source_id": "article_12345"
      }
    }'
  ```

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

  resp = requests.post(
      "https://api.factagora.com/api/v1/fingerprint/embed",
      headers={"Authorization": "Bearer fag_your_api_key"},
      json={
          "content": "The European Central Bank raised interest rates by 25 basis points on Thursday, citing persistent core inflation in the eurozone. Analysts at Goldman Sachs expect one more hike before a pause in Q4.",
          "content_type": "news",
          "metadata": {
              "author_id": "editor_jane",
              "published_at": "2024-06-15T08:00:00Z",
              "source_id": "article_12345",
          },
      },
  )
  data = resp.json()
  ```

  ```typescript TypeScript theme={null}
  const resp = await fetch("https://api.factagora.com/api/v1/fingerprint/embed", {
    method: "POST",
    headers: {
      Authorization: "Bearer fag_your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      content:
        "The European Central Bank raised interest rates by 25 basis points on Thursday, citing persistent core inflation in the eurozone. Analysts at Goldman Sachs expect one more hike before a pause in Q4.",
      content_type: "news",
      metadata: {
        author_id: "editor_jane",
        published_at: "2024-06-15T08:00:00Z",
        source_id: "article_12345",
      },
    }),
  });
  const data = await resp.json();
  ```
</CodeGroup>

### 응답

```json theme={null}
{
  "watermarked_content": "The European Central Bank raised interest rates by 25 basis points...",
  "fingerprint_id": "fp_l1p8OPCwGhvu",
  "tkg_snapshot": {
    "entities": ["European Central Bank", "Interest rate", "Goldman Sachs"],
    "timeseries": ["2024-06-15"],
    "relations": [
      { "from": "European Central Bank", "rel": "raises", "to": "Interest rate" }
    ],
    "argument_map": [
      {
        "premise": "Persistent core inflation in the eurozone",
        "evidence": "ECB policy meeting decision",
        "conclusion": "Interest rates raised by 25 basis points"
      }
    ]
  },
  "embed_timestamp": "2024-06-15T08:01:23.456Z",
  "meta": { "executionTimeMs": 1234 }
}
```

<Warning>
  **원본이 아니라 `watermarked_content`를 배포하세요.** 워터마크가 적용된 버전은 원본과 동일해 보이지만, 워터마크 기반 탐지를 가능하게 하는 보이지 않는 zero-width 문자들이 포함되어 있습니다.
</Warning>

<Info>
  **`fingerprint_id`를 내부 글 ID와 함께 저장하세요.** 재점수 산정과 리포팅에 필요합니다.
</Info>

## 2. 콘텐츠 재사용 탐지

당신의 글에서 비롯된 것처럼 보이는 콘텐츠를, 재작성되었더라도, 발견했다면 `/fingerprint/detect`에 보냅니다.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.factagora.com/api/v1/fingerprint/detect" \
    -H "Authorization: Bearer fag_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "content": "ECB hiked rates 25bp Thursday due to stubborn inflation. Goldman analysts predict one final increase before year-end pause."
    }'
  ```

  ```python Python theme={null}
  resp = requests.post(
      "https://api.factagora.com/api/v1/fingerprint/detect",
      headers={"Authorization": "Bearer fag_your_api_key"},
      json={
          "content": "ECB hiked rates 25bp Thursday due to stubborn inflation. Goldman analysts predict one final increase before year-end pause."
      },
  )
  result = resp.json()
  ```

  ```typescript TypeScript theme={null}
  const resp = await fetch("https://api.factagora.com/api/v1/fingerprint/detect", {
    method: "POST",
    headers: {
      Authorization: "Bearer fag_your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      content:
        "ECB hiked rates 25bp Thursday due to stubborn inflation. Goldman analysts predict one final increase before year-end pause.",
    }),
  });
  const result = await resp.json();
  ```
</CodeGroup>

### 응답

```json theme={null}
{
  "match_found": true,
  "confidence_score": 0.87,
  "query_fingerprint_id": "fp_tmpQueryId01",
  "matches": [
    {
      "fingerprint_id": "fp_l1p8OPCwGhvu",
      "content_type": "news",
      "metadata": { "author_id": "editor_jane", "source_id": "article_12345" },
      "embed_timestamp": "2024-06-15T08:01:23.456Z",
      "score": 0.87,
      "similarity_breakdown": {
        "entity_match": 0.92,
        "timeseries_match": 1.0,
        "causal_pattern_match": 0.78
      },
      "overlap": {
        "entities": ["european central bank", "interest rate", "goldman sachs"],
        "timeseries": ["2024-06-15"],
        "relations": ["european central bank|raises|interest rate"]
      },
      "watermark_match": false,
      "watermark_correlation": null
    }
  ],
  "meta": {
    "scanned": 156,
    "executionTimeMs": 342,
    "weights": { "entity": 0.5, "time": 0.2, "causal": 0.3 },
    "watermark_detected": false
  }
}
```

쿼리 텍스트가 완전히 재작성되었음에 주목하세요, "ECB hiked rates 25bp" vs "European Central Bank raised interest rates by 25 basis points", 그럼에도 API는 내부 인과 구조를 비교해 87%의 신뢰도로 매치를 찾아냈습니다.

## 3. 워터마크로 탐지 (최고 신뢰도)

콘텐츠의 워터마크 버전이 보이지 않는 문자들과 함께 그대로 복사되었다면, 워터마크 레이어가 발화해 거의 확실한 출처 증명을 제공합니다:

```json theme={null}
{
  "matches": [
    {
      "fingerprint_id": "fp_l1p8OPCwGhvu",
      "score": 0.87,
      "watermark_match": true,
      "watermark_correlation": 0.98,
      ...
    }
  ],
  "meta": {
    "watermark_detected": true
  }
}
```

`watermark_match: true`이면 매치는 암호학적으로 검증된 것입니다, 정확히 워터마크가 적용된 콘텐츠(또는 그 일부)가 사용되었음을 의미합니다.

## 4. 커스텀 가중치로 탐지 튜닝

콘텐츠 유형마다 점수 강조점이 달라질 수 있습니다. 필요하면 기본값을 재정의하세요:

<CodeGroup>
  ```json 법률 문서 (인과 구조 강조) theme={null}
  {
    "content": "...",
    "weights": { "entity": 0.3, "time": 0.1, "causal": 0.6 }
  }
  ```

  ```json 시간 민감 보고서 (타임라인 강조) theme={null}
  {
    "content": "...",
    "weights": { "entity": 0.3, "time": 0.5, "causal": 0.2 }
  }
  ```
</CodeGroup>

사용된 가중치는 항상 `meta.weights`에 반향되므로 어떤 값이 적용되었는지 확인할 수 있습니다.

## 5. 기존 fingerprint 재점수 산정

이미 삽입한 fingerprint에 새 콘텐츠가 매치되는지 주기적으로 확인하려면 `fingerprint_id`를 직접 전달하세요:

```bash theme={null}
curl -X POST "https://api.factagora.com/api/v1/fingerprint/detect" \
  -H "Authorization: Bearer fag_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"fingerprint_id": "fp_l1p8OPCwGhvu"}'
```

저장된 TKG 스냅샷을 재사용하므로 재추출 없이 더 빠르게 작동하고, 예약된 모니터링에 이상적입니다.

## 요약

| 단계       | 엔드포인트                                            | 역할                                     |
| -------- | ------------------------------------------------ | -------------------------------------- |
| Embed    | `POST /fingerprint/embed`                        | TKG 추출, 워터마크 삽입, fingerprint 저장        |
| Detect   | `POST /fingerprint/detect`                       | 저장된 fingerprint를 대상으로 워터마크 + TKG 매칭 실행 |
| Re-score | `POST /fingerprint/detect` (`fingerprint_id` 포함) | 기존 fingerprint를 새 후보 콘텐츠와 재점수 산정       |