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

> Extract claims, predictions, and causal edges from a URL, text, or file and store them in your knowledge graph.

Ingest external content, such as a URL, raw text, or uploaded file, and automatically extract structured knowledge (claims, predictions, causal edges) into your personal TKG (Temporal Knowledge Graph). Extracted knowledge is also stored as vector embeddings for semantic search.

## Endpoints

| Method | Path                  | Input                             |
| ------ | --------------------- | --------------------------------- |
| `POST` | `/api/v1/ingest`      | JSON body with `url` or `content` |
| `POST` | `/api/v1/ingest/file` | `multipart/form-data` with `file` |

***

## POST /api/v1/ingest

### Request Body

<ParamField body="url" type="string">
  URL to fetch and ingest. Either `url` or `content` is required.
</ParamField>

<ParamField body="content" type="string">
  Raw text content to ingest (max 20,000 characters). Either `url` or `content` is required.
</ParamField>

<ParamField body="visibility" type="string" default="private">
  Access control for the ingested content. `private` (default) is only accessible to you. `public` is accessible to anyone with your API key.
</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 Text 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 reported record revenue of $100B in Q4 2025. iPhone sales are expected to grow 15% in 2026.", "visibility": "private"}'
  ```
</RequestExample>

***

## POST /api/v1/ingest/file

### Request Body (multipart/form-data)

<ParamField body="file" type="file" required>
  PDF, Markdown, or TXT file to ingest.
</ParamField>

<ParamField body="visibility" type="string" default="private">
  Access control. `private` or `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>

***

## Response

<ResponseField name="ingest_source_id" type="string">
  Unique ID of the ingested source document.
</ResponseField>

<ResponseField name="tkg_id" type="string">
  ID of the TKG graph created for this document.
</ResponseField>

<ResponseField name="source_title" type="string">
  Title extracted from the source content.
</ResponseField>

<ResponseField name="claims" type="array">
  List of falsifiable factual statements extracted from the content.

  <Expandable title="Claim fields">
    <ResponseField name="title" type="string">Concise claim title</ResponseField>
    <ResponseField name="description" type="string">Full claim statement</ResponseField>
    <ResponseField name="category" type="string">Domain category (economics, technology, politics, etc.)</ResponseField>
    <ResponseField name="claim_date" type="string">Date the claim refers to (YYYY-MM-DD), if mentioned</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="predictions" type="array">
  List of future predictions extracted from the content.

  <Expandable title="Prediction fields">
    <ResponseField name="title" type="string">Concise prediction title</ResponseField>
    <ResponseField name="description" type="string">Full prediction statement</ResponseField>
    <ResponseField name="category" type="string">Domain category</ResponseField>
    <ResponseField name="deadline" type="string">Future deadline date (YYYY-MM-DD), if mentioned</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="edges" type="array">
  Causal relationships between extracted claims and predictions.

  <Expandable title="Edge fields">
    <ResponseField name="from_title" type="string">Title of the source node</ResponseField>
    <ResponseField name="to_title" type="string">Title of the target node</ResponseField>
    <ResponseField name="edge_type" type="string">Relationship type: `CAUSES`, `SUPPORTS`, `CONTRADICTS`, `TRIGGERS`, `CONTRIBUTING_FACTOR`, `PREVENTS`, `CONCURRENT_SIGNAL`, `QUALIFIES`, `DEPENDS_ON`, `DERIVED_FROM`, `SUPERSEDES`</ResponseField>
    <ResponseField name="confidence" type="number">Confidence score (0.0–1.0)</ResponseField>
    <ResponseField name="mechanism" type="string">Brief explanation of the causal relationship</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="general_length" type="number">
  Character length of the original content stored as vector chunks.
</ResponseField>

<ResponseField name="chunks_count" type="number">
  Number of vector chunks stored for semantic search.
</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": "Iran allowed to start oil exports immediately under interim deal",
        "description": "Iran would be allowed to start oil exports immediately under an interim deal with the US.",
        "category": "economics",
        "claim_date": "2026-06-17"
      }
    ],
    "predictions": [
      {
        "title": "Permanent peace negotiations following interim deal",
        "description": "Negotiations for a permanent peace are intended to address Tehran's nuclear activities.",
        "category": "politics",
        "deadline": null
      }
    ],
    "edges": [
      {
        "from_title": "Iran allowed to start oil exports immediately under interim deal",
        "to_title": "Permanent peace negotiations following interim deal",
        "edge_type": "TRIGGERS",
        "confidence": 0.7,
        "mechanism": "Oil export permission is a precondition enabling broader peace negotiations."
      }
    ],
    "general_length": 562,
    "chunks_count": 1
  }
  ```
</ResponseExample>

***

## Searching Ingested Content

Use `GET /api/v1/fact-search` with `source=ingest` to search your ingested content:

```bash theme={null}
curl "https://api.factagora.com/api/v1/fact-search?q=oil+exports+iran&source=ingest" \
  -H "Authorization: Bearer fag_your_api_key"
```

Results include chunks, claims, and predictions from your personal knowledge graph.