Skip to main content
POST
/
api
/
v1
/
ingest
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"}'

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

MethodPathInput
POST/api/v1/ingestJSON body with url or content
POST/api/v1/ingest/filemultipart/form-data with file

​
POST /api/v1/ingest

​
Request Body

​
url
string
URL to fetch and ingest. Either url or content is required.
​
content
string
Raw text content to ingest (max 20,000 characters). Either url or content is required.
​
visibility
string
default:"private"
Access control for the ingested content. private (default) — only accessible to you. public — accessible to anyone with your API key.
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"}'

​
POST /api/v1/ingest/file

​
Request Body (multipart/form-data)

​
file
file
required
PDF, Markdown, or TXT file to ingest.
​
visibility
string
default:"private"
Access control. private or public.
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"

​
Response

​
ingest_source_id
string
Unique ID of the ingested source document.
​
tkg_id
string
ID of the TKG graph created for this document.
​
source_title
string
Title extracted from the source content.
​
claims
array
List of falsifiable factual statements extracted from the content.
​
predictions
array
List of future predictions extracted from the content.
​
edges
array
Causal relationships between extracted claims and predictions.
​
general_length
number
Character length of the original content stored as vector chunks.
​
chunks_count
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 fag_your_api_key"
Results include chunks, claims, and predictions from your personal knowledge graph.