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

# Add URLs

> 컬렉션에 URL을 수집하고 진행 상태와 생성된 그래프를 확인합니다.

Collections는 여러 URL을 하나의 통합 지식 그래프(TKG)에 수집해 **브랜드별 프라이빗 코퍼스**를 구축합니다.

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

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

URL을 Collection의 통합 지식 그래프에 수집합니다. 각 URL은 크롤링 후 LLM이 클레임/예측/엣지를 추출해 TKG에 누적합니다.

**주의:** 수집은 동기로 처리되므로 모든 URL 처리가 완료된 후 응답이 반환됩니다. URL 하나당 10\~30초가 소요됩니다. 안정적인 처리를 위해 URL을 한 번에 하나씩 요청하는 것을 권장합니다.

### Request Body

<ParamField body="url" type="string" required>
  수집할 URL. 페이지를 크롤링 후 클레임/예측/엣지로 추출해 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 fa_your_personal_token" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://www.hyundai.com/uk/en/models/ioniq6.html"}'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "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
  }
  ```
</ResponseExample>

***

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

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

<RequestExample>
  ```bash cURL theme={null}
  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"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "deleted": true
  }
  ```
</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 fa_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 fa_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>