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

# Collections

> URL을 수집해 브랜드별 프라이빗 지식 그래프를 구축하고, 근거 기반 Q&A 및 검증 기능을 제공합니다.

Collections는 여러 URL을 하나의 통합 지식 그래프(TKG)에 수집해 **브랜드별 프라이빗 코퍼스**를 구축합니다. 구축된 코퍼스를 기반으로 질문에 답하거나 기존 Q\&A를 검증할 수 있습니다.

**개인 액세스 토큰(Personal Access Token)이 필요합니다.** 마스터 키는 사용할 수 없습니다.

## 엔드포인트

| Method   | Path                                     | 설명                         |
| -------- | ---------------------------------------- | -------------------------- |
| `POST`   | `/api/v1/collections`                    | Collection 생성              |
| `GET`    | `/api/v1/collections`                    | 내 Collection 목록 조회         |
| `GET`    | `/api/v1/collections/{id}`               | Collection 상세 + 수집된 URL 목록 |
| `DELETE` | `/api/v1/collections/{id}`               | Collection 및 모든 데이터 삭제     |
| `POST`   | `/api/v1/collections/{id}/ingest`        | URL 비동기 수집 큐에 추가           |
| `GET`    | `/api/v1/collections/{id}/ingest-status` | 수집 진행 상황 폴링                |
| `GET`    | `/api/v1/collections/{id}/graph`         | 통합 지식 그래프 조회               |
| `POST`   | `/api/v1/collections/{id}/answer`        | Collection 기반 근거 답변        |
| `POST`   | `/api/v1/collections/{id}/qa-verify`     | 기존 Q\&A 검증                 |

***

## POST /api/v1/collections

새 Collection(브랜드 코퍼스)을 생성합니다.

### Request Body

<ParamField body="name" type="string" required>
  Collection 이름. 예: `"Hyundai UK"`
</ParamField>

<ParamField body="slug" type="string">
  선택적 URL 친화적 식별자. 예: `"hyundai-uk"`
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.factagora.com/api/v1/collections" \
    -H "Authorization: Bearer fag_your_personal_token" \
    -H "Content-Type: application/json" \
    -d '{"name": "Hyundai UK"}'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "5966a861-6952-482a-a9d0-041ad5d2a667",
    "name": "Hyundai UK",
    "slug": null,
    "status": "active",
    "created_at": "2026-06-29T01:34:47.817583+00:00"
  }
  ```
</ResponseExample>

***

## GET /api/v1/collections

인증된 사용자의 모든 Collection 목록을 반환합니다.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.factagora.com/api/v1/collections" \
    -H "Authorization: Bearer fag_your_personal_token"
  ```
</RequestExample>

***

## GET /api/v1/collections/{id}

Collection 상세 정보와 수집된 URL 목록 및 처리 상태를 반환합니다.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.factagora.com/api/v1/collections/5966a861-6952-482a-a9d0-041ad5d2a667" \
    -H "Authorization: Bearer fag_your_personal_token"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "5966a861-6952-482a-a9d0-041ad5d2a667",
    "name": "Hyundai UK",
    "slug": null,
    "status": "active",
    "created_at": "2026-06-29T01:34:47.817583+00:00",
    "sources": [
      {
        "ingest_source_id": "a5e00acc-aa4a-4ba6-bc44-1409fe64ef81",
        "url": "https://www.hyundai.com/uk/en/models/ioniq6.html",
        "status": "completed",
        "created_at": "2026-06-29T02:00:30.000000+00:00"
      }
    ]
  }
  ```
</ResponseExample>

***

## DELETE /api/v1/collections/{id}

Collection과 연결된 모든 데이터(sources, chunks, claims, predictions, TKG)를 삭제합니다.

<RequestExample>
  ```bash cURL theme={null}
  curl -X DELETE "https://api.factagora.com/api/v1/collections/5966a861-6952-482a-a9d0-041ad5d2a667" \
    -H "Authorization: Bearer fag_your_personal_token"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "deleted": true
  }
  ```
</ResponseExample>

***

## POST /api/v1/collections/{id}/ingest

URL을 Collection의 통합 지식 그래프에 수집하도록 큐에 추가합니다. `202 Accepted`를 즉시 반환하며 실제 수집은 백그라운드에서 실행됩니다. `/ingest-status`로 진행 상황을 폴링하세요.

### Request Body

<ParamField body="urls" type="string[]" required>
  수집할 URL 목록 (1–50개). 각 URL은 크롤링 후 claims/predictions/edges로 추출되어 TKG에 누적됩니다.
</ParamField>

<ParamField body="visibility" type="string" default="private">
  수집 콘텐츠 접근 권한. `private` 또는 `public`.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.factagora.com/api/v1/collections/5966a861-6952-482a-a9d0-041ad5d2a667/ingest" \
    -H "Authorization: Bearer fag_your_personal_token" \
    -H "Content-Type: application/json" \
    -d '{
      "urls": [
        "https://www.hyundai.com/uk/en/models/ioniq6.html",
        "https://www.hyundai.com/uk/en/models/ioniq6/trims-prices.html"
      ]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 202 theme={null}
  {
    "collection_id": "5966a861-6952-482a-a9d0-041ad5d2a667",
    "queued": 2,
    "ingest_source_ids": [
      "a5e00acc-aa4a-4ba6-bc44-1409fe64ef81",
      "b1343b92-defb-4818-aec2-5ed4299f704b"
    ]
  }
  ```
</ResponseExample>

***

## GET /api/v1/collections/{id}/ingest-status

Collection에 수집된 모든 URL의 처리 상태를 반환합니다.

### 상태값

| 상태           | 의미                             |
| ------------ | ------------------------------ |
| `processing` | 수집 진행 중                        |
| `completed`  | 수집 완료                          |
| `failed`     | 수집 실패 (URL 접근 불가 또는 콘텐츠 추출 오류) |

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.factagora.com/api/v1/collections/5966a861-6952-482a-a9d0-041ad5d2a667/ingest-status" \
    -H "Authorization: Bearer fag_your_personal_token"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "collection_id": "5966a861-6952-482a-a9d0-041ad5d2a667",
    "sources": [
      {
        "ingest_source_id": "a5e00acc-aa4a-4ba6-bc44-1409fe64ef81",
        "url": "https://www.hyundai.com/uk/en/models/ioniq6.html",
        "status": "completed",
        "created_at": "2026-06-29T02:00:30.000000+00:00"
      },
      {
        "ingest_source_id": "b1343b92-defb-4818-aec2-5ed4299f704b",
        "url": "https://www.hyundai.com/uk/en/models/ioniq6/trims-prices.html",
        "status": "processing",
        "created_at": "2026-06-29T02:00:30.000000+00:00"
      }
    ],
    "summary": {
      "total": 2,
      "processing": 1,
      "completed": 1,
      "failed": 0
    }
  }
  ```
</ResponseExample>

***

## GET /api/v1/collections/{id}/graph

Collection의 통합 지식 그래프를 노드와 엣지 형태로 반환합니다. 그래프 시각화에 사용할 수 있습니다.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.factagora.com/api/v1/collections/5966a861-6952-482a-a9d0-041ad5d2a667/graph" \
    -H "Authorization: Bearer fag_your_personal_token"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "nodes": [
      {
        "id": "13c7afac-ea6f-44b4-807e-01c7935a8bfc",
        "label": "IONIQ 6 electric range up to 338 miles",
        "type": "CLAIM"
      },
      {
        "id": "7872d682-7c9c-43ba-a3e6-6a729b57ce06",
        "label": "Hyundai Electric Vehicle Range Will Expand and Improve",
        "type": "PREDICTION"
      }
    ],
    "edges": [
      {
        "from": "13c7afac-ea6f-44b4-807e-01c7935a8bfc",
        "to": "7872d682-7c9c-43ba-a3e6-6a729b57ce06",
        "label": "SUPPORTS"
      }
    ]
  }
  ```
</ResponseExample>

***

## POST /api/v1/collections/{id}/answer

Collection의 지식 그래프만을 근거로 질문에 답변합니다. pgvector 시맨틱 검색으로 관련 내용을 먼저 추린 후 답변을 생성합니다.

지식 그래프에 충분한 정보가 없으면 `grounded: false`를 반환해 환각을 방지합니다.

### Request Body

<ParamField body="question" type="string" required>
  답변할 질문.
</ParamField>

<ParamField body="language" type="string" default="English">
  답변 언어. 예: `"Korean"`, `"Japanese"`
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.factagora.com/api/v1/collections/5966a861-6952-482a-a9d0-041ad5d2a667/answer" \
    -H "Authorization: Bearer fag_your_personal_token" \
    -H "Content-Type: application/json" \
    -d '{"question": "IONIQ 6의 주행 가능 거리는?", "language": "Korean"}'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "question": "IONIQ 6의 주행 가능 거리는?",
    "answer": "IONIQ 6는 최대 338마일(약 544km)의 주행 가능 거리를 제공합니다.",
    "grounded": true,
    "sources": [
      {
        "url": "https://www.hyundai.com/uk/en/models/ioniq6.html",
        "title": "IONIQ 6 | Hyundai UK"
      }
    ],
    "meta": {
      "executionTimeMs": 1285
    }
  }
  ```
</ResponseExample>

***

## POST /api/v1/collections/{id}/qa-verify

기존 Q\&A 쌍을 Collection 지식 그래프와 비교해 검증합니다. 각 쌍에 대해 세 가지 판정 중 하나를 반환합니다.

| 판정            | 의미                                           |
| ------------- | -------------------------------------------- |
| `correct`     | 답변이 지식 그래프의 내용과 일치함                          |
| `incorrect`   | 답변이 지식 그래프와 모순됨 — `correction` 필드에 올바른 답변 제공 |
| `unsupported` | Collection에 검증에 충분한 정보가 없음                   |

### Request Body

<ParamField body="qa_pairs" type="array" required>
  검증할 Q\&A 쌍 목록 (1–50개).

  <Expandable title="qa_pairs 필드">
    <ParamField body="question" type="string" required>질문</ParamField>
    <ParamField body="answer" type="string" required>검증할 답변</ParamField>
  </Expandable>
</ParamField>

<ParamField body="language" type="string" default="English">
  판정 요약 및 수정 답변 언어.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.factagora.com/api/v1/collections/5966a861-6952-482a-a9d0-041ad5d2a667/qa-verify" \
    -H "Authorization: Bearer fag_your_personal_token" \
    -H "Content-Type: application/json" \
    -d '{
      "qa_pairs": [
        {
          "question": "IONIQ 6 충전 시간은?",
          "answer": "IONIQ 6는 10%에서 80%까지 18~36분 만에 충전됩니다."
        },
        {
          "question": "IONIQ 6는 가솔린 차량인가요?",
          "answer": "네, IONIQ 6는 가솔린 차량입니다."
        }
      ],
      "language": "Korean"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "results": [
      {
        "question": "IONIQ 6 충전 시간은?",
        "answer": "IONIQ 6는 10%에서 80%까지 18~36분 만에 충전됩니다.",
        "verdict": "correct",
        "confidence": 0.92,
        "correction": null,
        "summary": "지식 그래프에 따르면 IONIQ 6는 350kW 초고속 충전기로 10%에서 80%까지 18~36분 충전이 확인됩니다."
      },
      {
        "question": "IONIQ 6는 가솔린 차량인가요?",
        "answer": "네, IONIQ 6는 가솔린 차량입니다.",
        "verdict": "incorrect",
        "confidence": 0.95,
        "correction": "IONIQ 6는 완전한 전기차입니다. 가솔린 버전은 없습니다.",
        "summary": "지식 그래프는 IONIQ 6를 순수 전기차로만 설명하고 있습니다."
      }
    ],
    "meta": {
      "executionTimeMs": 2100
    }
  }
  ```
</ResponseExample>