Add URLs

Collections let you build a per-brand private corpus by ingesting multiple URLs into one unified knowledge graph (TKG). Requires a personal access token. Master keys are rejected.

POST /api/v1/collections//ingest

Ingest one or more URLs into the collection’s unified knowledge graph. Each URL is fetched, parsed by LLM, and its claims/predictions/edges are extracted and accumulated into the collection TKG. Note: Ingestion is synchronous: the request completes only after all URLs are processed. Each URL typically takes 10–30 seconds. Send URLs one at a time for best reliability.

Request Body

string

required

URL to ingest. The page is crawled and its claims/predictions/edges are extracted into the collection TKG.

string

default:"private"

Access control for the ingested content. private or public.

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

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

DELETE /api/v1/collections//sources/

Remove a source URL from the collection (soft detach). The source’s extracted claims, predictions, and chunks are retained in the database but are no longer associated with this collection.

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"

{
  "deleted": true
}

GET /api/v1/collections//ingest-status

Poll the ingestion status for all URLs in the collection.

Status values

Status	Meaning
`processing`	Ingestion in progress
`completed`	Successfully ingested
`failed`	Ingestion failed (e.g. URL unreachable or content extraction error)

curl "https://api.factagora.com/api/v1/collections/5966a861-6952-482a-a9d0-041ad5d2a667/ingest-status" \
  -H "Authorization: Bearer fa_your_personal_token"

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

GET /api/v1/collections//graph

Get the collection’s unified knowledge graph as nodes and edges, shaped for graph visualization.

curl "https://api.factagora.com/api/v1/collections/5966a861-6952-482a-a9d0-041ad5d2a667/graph" \
  -H "Authorization: Bearer fa_your_personal_token"

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

Overview

Endpoints

Best Practices

POST /api/v1/collections//ingest

Request Body

DELETE /api/v1/collections//sources/

GET /api/v1/collections//ingest-status

Status values

GET /api/v1/collections//graph

​POST /api/v1/collections//ingest

​Request Body

​DELETE /api/v1/collections//sources/

​GET /api/v1/collections//ingest-status

​Status values

​GET /api/v1/collections//graph

POST /api/v1/collections//ingest

Request Body

DELETE /api/v1/collections//sources/

GET /api/v1/collections//ingest-status

Status values

GET /api/v1/collections//graph