Skip to main content
Collections let you build a per-brand private corpus by ingesting multiple URLs into one unified knowledge graph (TKG). Once built, you can ask questions grounded only in that corpus, or verify existing Q&A pairs against it. Requires a personal access token. Master keys are rejected.

​
Endpoints

MethodPathDescription
POST/api/v1/collectionsCreate a collection
GET/api/v1/collectionsList your collections
GET/api/v1/collections/{id}Get collection details + ingested URLs
DELETE/api/v1/collections/{id}Delete a collection and all its data
POST/api/v1/collections/{id}/ingestIngest URLs into the collection
GET/api/v1/collections/{id}/ingest-statusPoll ingestion progress
DELETE/api/v1/collections/{id}/sources/{sourceId}Remove a source URL from the collection
GET/api/v1/collections/{id}/graphGet the unified knowledge graph
POST/api/v1/collections/{id}/answerAsk a question grounded in the collection
POST/api/v1/collections/{id}/qa-verifyVerify existing Q&A pairs

​
POST /api/v1/collections

Create a new collection (brand corpus).

​
Request Body

​
name
string
required
Collection name, e.g. "Hyundai UK".
​
slug
string
Optional URL-friendly identifier, e.g. "hyundai-uk".
curl -X POST "https://api.factagora.com/api/v1/collections" \
  -H "Authorization: Bearer fag_your_personal_token" \
  -H "Content-Type: application/json" \
  -d '{"name": "Hyundai UK"}'

{
  "id": "5966a861-6952-482a-a9d0-041ad5d2a667",
  "name": "Hyundai UK",
  "slug": null,
  "status": "active",
  "created_at": "2026-06-29T01:34:47.817583+00:00"
}

​
GET /api/v1/collections

List all collections owned by the authenticated user. 
curl "https://api.factagora.com/api/v1/collections" \
  -H "Authorization: Bearer fag_your_personal_token"

​
GET /api/v1/collections/

Get a collection including its ingested URL list and their processing status. 
curl "https://api.factagora.com/api/v1/collections/5966a861-6952-482a-a9d0-041ad5d2a667" \
  -H "Authorization: Bearer fag_your_personal_token"

{
  "id": "5966a861-6952-482a-a9d0-041ad5d2a667",
  "name": "Hyundai UK",
  "slug": null,
  "status": "active",
  "created_at": "2026-06-29T01:34:47.817583+00:00",
  "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"
    }
  ]
}

​
DELETE /api/v1/collections/

Delete a collection and all its associated data (sources, chunks, claims, predictions, TKG). 
curl -X DELETE "https://api.factagora.com/api/v1/collections/5966a861-6952-482a-a9d0-041ad5d2a667" \
  -H "Authorization: Bearer fag_your_personal_token"

{
  "deleted": true
}

​
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

​
url
string
required
URL to ingest. The page is crawled and its claims/predictions/edges are extracted into the collection TKG.
​
visibility
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 fag_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 fag_your_personal_token"

{
  "deleted": true
}

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

Poll the ingestion status for all URLs in the collection.

​
Status values

StatusMeaning
processingIngestion in progress
completedSuccessfully ingested
failedIngestion 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 fag_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 fag_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"
    }
  ]
}

​
POST /api/v1/collections//answer

Ask a question and get an answer grounded only in this collection’s knowledge graph. Uses semantic search (pgvector) to retrieve the most relevant content before generating an answer. If the knowledge graph does not contain enough information to answer, grounded is set to false to prevent hallucination.

​
Request Body

​
question
string
required
The question to answer.
​
language
string
default:"English"
Language for the answer (e.g. "Korean", "Japanese").
curl -X POST "https://api.factagora.com/api/v1/collections/5966a861-6952-482a-a9d0-041ad5d2a667/answer" \
  -H "Authorization: Bearer fag_your_personal_token" \
  -H "Content-Type: application/json" \
  -d '{"question": "What is the IONIQ 6 electric range?"}'

{
  "question": "What is the IONIQ 6 electric range?",
  "answer": "The IONIQ 6 has a driving range of up to 338 miles.",
  "grounded": true,
  "sources": [
    {
      "url": "https://www.hyundai.com/uk/en/models/ioniq6.html",
      "title": "IONIQ 6 | Hyundai UK"
    }
  ],
  "meta": {
    "executionTimeMs": 1285
  }
}

​
POST /api/v1/collections//qa-verify

Verify existing Q&A pairs against the collection knowledge graph. Each pair receives one of three verdicts:
VerdictMeaning
correctThe answer is supported by the collection’s knowledge
incorrectThe answer contradicts the knowledge, so a correction is provided
unsupportedThe collection does not have enough information to verify

​
Request Body

​
qa_pairs
array
required
Array of question/answer pairs to verify (1–50).
​
language
string
default:"English"
Language for verdict summaries and corrections.
curl -X POST "https://api.factagora.com/api/v1/collections/5966a861-6952-482a-a9d0-041ad5d2a667/qa-verify" \
  -H "Authorization: Bearer fag_your_personal_token" \
  -H "Content-Type: application/json" \
  -d '{
    "qa_pairs": [
      {
        "question": "What is the IONIQ 6 charging time?",
        "answer": "The IONIQ 6 charges from 10% to 80% in 18 to 36 minutes."
      },
      {
        "question": "Is the IONIQ 6 available as a petrol car?",
        "answer": "Yes, the IONIQ 6 is available as a petrol car."
      }
    ]
  }'

{
  "results": [
    {
      "question": "What is the IONIQ 6 charging time?",
      "answer": "The IONIQ 6 charges from 10% to 80% in 18 to 36 minutes.",
      "verdict": "correct",
      "confidence": 0.92,
      "correction": null,
      "summary": "The collection confirms IONIQ 6 charges from 10% to 80% in 18–36 minutes on a 350 kW ultra-fast charger."
    },
    {
      "question": "Is the IONIQ 6 available as a petrol car?",
      "answer": "Yes, the IONIQ 6 is available as a petrol car.",
      "verdict": "incorrect",
      "confidence": 0.95,
      "correction": "The IONIQ 6 is a fully electric vehicle. No petrol variant is available.",
      "summary": "The collection describes the IONIQ 6 exclusively as an electric car."
    }
  ],
  "meta": {
    "executionTimeMs": 2100
  }
}