Ingest

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

POST

api

ingest

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

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

string

URL to fetch and ingest. Either url or content is required.

string

Raw text content to ingest (max 20,000 characters). Either url or content is required.

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.

cURL

curl -X POST "https://api.factagora.com/api/v1/ingest" \
  -H "Authorization: Bearer fa_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/quarterly-report"}'

Python

import requests

resp = requests.post(
    "https://api.factagora.com/api/v1/ingest",
    headers={"Authorization": "Bearer fa_your_api_key"},
    json={"url": "https://example.com/quarterly-report"},
)
data = resp.json()

TypeScript

const resp = await fetch("https://api.factagora.com/api/v1/ingest", {
  method: "POST",
  headers: {
    Authorization: "Bearer fa_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ url: "https://example.com/quarterly-report" }),
});
const data = await resp.json();

POST /api/v1/ingest/file

Request Body (multipart/form-data)

file

required

PDF, Markdown, or TXT file to ingest.

string

default:"private"

Access control. private or public.

curl -X POST "https://api.factagora.com/api/v1/ingest/file" \
  -H "Authorization: Bearer fa_your_api_key" \
  -F "file=@report.pdf" \
  -F "visibility=private"

Response

string

Unique ID of the ingested source document.

string

ID of the TKG graph created for this document.

string

Title extracted from the source content.

array

List of falsifiable factual statements extracted from the content.

Show Claim fields

string

Concise claim title

string

Full claim statement

string

Domain category (economics, technology, politics, etc.)

string

Date the claim refers to (YYYY-MM-DD), if mentioned

array

List of future predictions extracted from the content.

Show Prediction fields

string

Concise prediction title

string

Full prediction statement

string

Domain category

string

Future deadline date (YYYY-MM-DD), if mentioned

array

Causal relationships between extracted claims and predictions.

Show Edge fields

string

Title of the source node

string

Title of the target node

string

Relationship type: CAUSES, SUPPORTS, CONTRADICTS, TRIGGERS, CONTRIBUTING_FACTOR, PREVENTS, CONCURRENT_SIGNAL, QUALIFIES, DEPENDS_ON, DERIVED_FROM, SUPERSEDES

number

Confidence score (0.0–1.0)

string

Brief explanation of the causal relationship

number

Character length of the original content stored as vector chunks.

number

Number of vector chunks stored for semantic search.

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

Searching Ingested Content

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

curl "https://api.factagora.com/api/v1/fact-search?q=oil+exports+iran&source=ingest" \
  -H "Authorization: Bearer fa_your_api_key"

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

Overview

Endpoints

Best Practices

Endpoints

POST /api/v1/ingest

Request Body

POST /api/v1/ingest/file

Request Body (multipart/form-data)

Response

Searching Ingested Content

​Endpoints

​POST /api/v1/ingest

​Request Body

​POST /api/v1/ingest/file

​Request Body (multipart/form-data)

​Response

​Searching Ingested Content

Endpoints

POST /api/v1/ingest

Request Body

POST /api/v1/ingest/file

Request Body (multipart/form-data)

Response

Searching Ingested Content