Collections

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`	수집 진행 상황 폴링
`DELETE`	`/api/v1/collections/{id}/sources/{sourceId}`	Collection에서 URL 제거
`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

string

필수

Collection 이름. 예: "Hyundai UK"

string

선택적 URL 친화적 식별자. 예: "hyundai-uk"

cURL

curl -X POST "https://api.factagora.com/api/v1/collections/{id}/answer" \
  -H "Authorization: Bearer fa_your_personal_token" \
  -H "Content-Type: application/json" \
  -d '{"question": "What is the IONIQ 6 electric range?"}'

Python

import requests

resp = requests.post(
    f"https://api.factagora.com/api/v1/collections/{collection_id}/answer",
    headers={"Authorization": "Bearer fa_your_personal_token"},
    json={"question": "What is the IONIQ 6 electric range?"},
)
data = resp.json()

TypeScript

const resp = await fetch(
  `https://api.factagora.com/api/v1/collections/${collectionId}/answer`,
  {
    method: "POST",
    headers: {
      Authorization: "Bearer fa_your_personal_token",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ question: "What is the IONIQ 6 electric range?" }),
  },
);
const data = await resp.json();

{
  "id": "5966a861-6952-482a-a9d0-041ad5d2a667",
  "name": "Hyundai UK",
  "slug": null,
  "status": "active",
  "created_at": "2026-06-29T01:34:47.817583+00:00"
}

GET /api/v1/collections

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

curl "https://api.factagora.com/api/v1/collections" \
  -H "Authorization: Bearer fa_your_personal_token"

GET /api/v1/collections/

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

curl "https://api.factagora.com/api/v1/collections/5966a861-6952-482a-a9d0-041ad5d2a667" \
  -H "Authorization: Bearer fa_your_personal_token"

{
  "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"
    }
  ]
}

DELETE /api/v1/collections/

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

curl -X DELETE "https://api.factagora.com/api/v1/collections/5966a861-6952-482a-a9d0-041ad5d2a667" \
  -H "Authorization: Bearer fa_your_personal_token"

{
  "deleted": true
}

POST /api/v1/collections//ingest

URL을 Collection의 통합 지식 그래프에 수집합니다. 각 URL은 크롤링 후 LLM이 클레임/예측/엣지를 추출해 TKG에 누적합니다. 주의: 수집은 동기로 처리되므로 모든 URL 처리가 완료된 후 응답이 반환됩니다. URL 하나당 10~30초가 소요됩니다. 안정적인 처리를 위해 URL을 한 번에 하나씩 요청하는 것을 권장합니다.

Request Body

string

필수

수집할 URL. 페이지를 크롤링 후 클레임/예측/엣지로 추출해 TKG에 누적합니다.

string

기본값:"private"

수집 콘텐츠 접근 권한. private 또는 public.

curl -X POST "https://api.factagora.com/api/v1/collections/5966a861-6952-482a-a9d0-041ad5d2a667/ingest" \
  -H "Authorization: Bearer fa_your_personal_token" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.hyundai.com/uk/en/models/ioniq6.html"}'

{
  "collection_id": "5966a861-6952-482a-a9d0-041ad5d2a667",
  "tkg_id": "a97a1a3c-2d52-4c17-af83-1332e826af8d",
  "url": "https://www.hyundai.com/uk/en/models/ioniq6.html",
  "status": "completed",
  "ingest_source_id": "a5e00acc-aa4a-4ba6-bc44-1409fe64ef81",
  "claims_count": 18,
  "predictions_count": 2
}

DELETE /api/v1/collections//sources/

Collection에서 URL을 제거합니다 (소프트 분리). 해당 source의 claims, predictions, chunks 데이터는 유지되지만 이 Collection과의 연결이 끊깁니다.

curl -X DELETE "https://api.factagora.com/api/v1/collections/5966a861-6952-482a-a9d0-041ad5d2a667/sources/a5e00acc-aa4a-4ba6-bc44-1409fe64ef81" \
  -H "Authorization: Bearer fa_your_personal_token"

{
  "deleted": true
}

GET /api/v1/collections//ingest-status

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

상태값

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

curl "https://api.factagora.com/api/v1/collections/5966a861-6952-482a-a9d0-041ad5d2a667/ingest-status" \
  -H "Authorization: Bearer fa_your_personal_token"

{
  "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
  }
}

GET /api/v1/collections//graph

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

curl "https://api.factagora.com/api/v1/collections/5966a861-6952-482a-a9d0-041ad5d2a667/graph" \
  -H "Authorization: Bearer fa_your_personal_token"

{
  "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"
    }
  ]
}

POST /api/v1/collections//answer

Collection의 지식 그래프만을 근거로 질문에 답변합니다. pgvector 시맨틱 검색으로 관련 내용을 먼저 추린 후 답변을 생성합니다. 지식 그래프에 충분한 정보가 없으면 grounded: false를 반환해 환각을 방지합니다.

Request Body

string

필수

답변할 질문.

string

기본값:"English"

답변 언어. 예: "Korean", "Japanese"

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

{
  "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
  }
}

POST /api/v1/collections//qa-verify

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

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

Request Body

array

필수

검증할 Q&A 쌍 목록 (1–50개).

표시 qa_pairs 필드

string

필수

질문

string

필수

검증할 답변

string

기본값:"English"

판정 요약 및 수정 답변 언어.

curl -X POST "https://api.factagora.com/api/v1/collections/5966a861-6952-482a-a9d0-041ad5d2a667/qa-verify" \
  -H "Authorization: Bearer fa_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"
  }'

{
  "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
  }
}

개요

Endpoints

Best Practices

엔드포인트

POST /api/v1/collections

Request Body

GET /api/v1/collections

GET /api/v1/collections/

DELETE /api/v1/collections/

POST /api/v1/collections//ingest

Request Body

DELETE /api/v1/collections//sources/

GET /api/v1/collections//ingest-status

상태값

GET /api/v1/collections//graph

POST /api/v1/collections//answer

Request Body

POST /api/v1/collections//qa-verify

Request Body

​엔드포인트

​POST /api/v1/collections

​Request Body

​GET /api/v1/collections

​GET /api/v1/collections/

​DELETE /api/v1/collections/

​POST /api/v1/collections//ingest

​Request Body

​DELETE /api/v1/collections//sources/

​GET /api/v1/collections//ingest-status

​상태값

​GET /api/v1/collections//graph

​POST /api/v1/collections//answer

​Request Body

​POST /api/v1/collections//qa-verify

​Request Body

엔드포인트

POST /api/v1/collections

Request Body

GET /api/v1/collections

GET /api/v1/collections/

DELETE /api/v1/collections/

POST /api/v1/collections//ingest

Request Body

DELETE /api/v1/collections//sources/

GET /api/v1/collections//ingest-status

상태값

GET /api/v1/collections//graph

POST /api/v1/collections//answer

Request Body

POST /api/v1/collections//qa-verify

Request Body