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

# Ingest

> URL, 텍스트, 파일에서 클레임, 예측, 인과 관계를 추출하여 지식 그래프에 저장합니다.

외부 콘텐츠(URL, 텍스트, 파일)를 수집하여 구조화된 지식(클레임, 예측, 인과 엣지)을 개인 TKG(Temporal Knowledge Graph)에 자동으로 추출·저장합니다. 추출된 지식은 시맨틱 검색을 위해 벡터 임베딩으로도 저장됩니다.

## 엔드포인트

| 메서드    | 경로                    | 입력                                |
| ------ | --------------------- | --------------------------------- |
| `POST` | `/api/v1/ingest`      | `url` 또는 `content`가 포함된 JSON 바디   |
| `POST` | `/api/v1/ingest/file` | `file`이 포함된 `multipart/form-data` |

***

## POST /api/v1/ingest

### 요청 바디

<ParamField body="url" type="string">
  수집할 URL. `url` 또는 `content` 중 하나는 필수입니다.
</ParamField>

<ParamField body="content" type="string">
  수집할 원본 텍스트 (최대 20,000자). `url` 또는 `content` 중 하나는 필수입니다.
</ParamField>

<ParamField body="visibility" type="string" default="private">
  접근 제어 설정. `private`은 기본값이며 본인만 접근 가능하고, `public`은 공개 접근을 허용합니다.
</ParamField>

<RequestExample>
  ```bash URL theme={null}
  curl -X POST "https://api.factagora.com/api/v1/ingest" \
    -H "Authorization: Bearer fag_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://www.reuters.com/article/...", "visibility": "private"}'
  ```

  ```bash 텍스트 theme={null}
  curl -X POST "https://api.factagora.com/api/v1/ingest" \
    -H "Authorization: Bearer fag_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{"content": "Apple은 2025년 4분기에 1,000억 달러의 사상 최대 매출을 기록했습니다. 2026년에는 iPhone 판매량이 15% 성장할 것으로 예상됩니다.", "visibility": "private"}'
  ```
</RequestExample>

***

## POST /api/v1/ingest/file

### 요청 바디 (multipart/form-data)

<ParamField body="file" type="file" required>
  수집할 PDF, Markdown, 또는 TXT 파일.
</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/ingest/file" \
    -H "Authorization: Bearer fag_your_api_key" \
    -F "file=@report.pdf" \
    -F "visibility=private"
  ```
</RequestExample>

***

## 응답

<ResponseField name="ingest_source_id" type="string">
  수집된 소스 문서의 고유 ID.
</ResponseField>

<ResponseField name="tkg_id" type="string">
  이 문서를 위해 생성된 TKG 그래프 ID.
</ResponseField>

<ResponseField name="source_title" type="string">
  소스 콘텐츠에서 추출된 제목.
</ResponseField>

<ResponseField name="claims" type="array">
  콘텐츠에서 추출된 검증 가능한 사실 진술 목록.

  <Expandable title="Claim 필드">
    <ResponseField name="title" type="string">간결한 클레임 제목</ResponseField>
    <ResponseField name="description" type="string">전체 클레임 내용</ResponseField>
    <ResponseField name="category" type="string">도메인 카테고리 (economics, technology, politics 등)</ResponseField>
    <ResponseField name="claim_date" type="string">클레임이 참조하는 날짜 (YYYY-MM-DD), 언급된 경우</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="predictions" type="array">
  콘텐츠에서 추출된 미래 예측 목록.

  <Expandable title="Prediction 필드">
    <ResponseField name="title" type="string">간결한 예측 제목</ResponseField>
    <ResponseField name="description" type="string">전체 예측 내용</ResponseField>
    <ResponseField name="category" type="string">도메인 카테고리</ResponseField>
    <ResponseField name="deadline" type="string">미래 마감일 (YYYY-MM-DD), 언급된 경우</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="edges" type="array">
  추출된 클레임과 예측 간의 인과 관계.

  <Expandable title="Edge 필드">
    <ResponseField name="from_title" type="string">소스 노드 제목</ResponseField>
    <ResponseField name="to_title" type="string">타겟 노드 제목</ResponseField>
    <ResponseField name="edge_type" type="string">관계 타입: `CAUSES`, `SUPPORTS`, `CONTRADICTS`, `TRIGGERS`, `CONTRIBUTING_FACTOR`, `PREVENTS`, `CONCURRENT_SIGNAL`, `QUALIFIES`, `DEPENDS_ON`, `DERIVED_FROM`, `SUPERSEDES`</ResponseField>
    <ResponseField name="confidence" type="number">신뢰도 점수 (0.0–1.0)</ResponseField>
    <ResponseField name="mechanism" type="string">인과 관계에 대한 간략한 설명</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="general_length" type="number">
  벡터 청크로 저장된 원본 콘텐츠의 문자 수.
</ResponseField>

<ResponseField name="chunks_count" type="number">
  시맨틱 검색을 위해 저장된 벡터 청크 수.
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "ingest_source_id": "cec6ad87-b783-4b4e-a6f4-65130b5e17a8",
    "tkg_id": "a6c36ed6-36e3-4f87-8855-e88484f3a08f",
    "source_title": "Iran to Gain Major Financial Relief Under Interim Deal With US",
    "claims": [
      {
        "title": "이란, 임시 협정 하에 즉시 석유 수출 허용",
        "description": "이란은 미국과의 임시 협정 하에 즉시 석유 수출을 시작할 수 있게 됩니다.",
        "category": "economics",
        "claim_date": "2026-06-17"
      }
    ],
    "predictions": [
      {
        "title": "임시 협정 이후 영구 평화 협상 진행",
        "description": "테헤란의 핵 활동을 다루기 위한 영구 평화 협상이 진행될 예정입니다.",
        "category": "politics",
        "deadline": null
      }
    ],
    "edges": [
      {
        "from_title": "이란, 임시 협정 하에 즉시 석유 수출 허용",
        "to_title": "임시 협정 이후 영구 평화 협상 진행",
        "edge_type": "TRIGGERS",
        "confidence": 0.7,
        "mechanism": "석유 수출 허가가 광범위한 평화 협상을 가능하게 하는 전제 조건입니다."
      }
    ],
    "general_length": 562,
    "chunks_count": 1
  }
  ```
</ResponseExample>

***

## 수집된 콘텐츠 검색

`GET /api/v1/fact-search`에 `source=ingest` 파라미터를 사용하여 개인 지식 그래프를 검색하세요:

```bash theme={null}
curl "https://api.factagora.com/api/v1/fact-search?q=석유+수출+이란&source=ingest" \
  -H "Authorization: Bearer fag_your_api_key"
```

결과에는 개인 지식 그래프의 청크, 클레임, 예측이 포함됩니다.