Collections

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

Method	Path	Description
`POST`	`/api/v1/collections`	Create a collection
`GET`	`/api/v1/collections`	List 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}/ingest`	Ingest URLs into the collection
`GET`	`/api/v1/collections/{id}/ingest-status`	Poll ingestion progress
`DELETE`	`/api/v1/collections/{id}/sources/{sourceId}`	Remove a source URL from the collection
`GET`	`/api/v1/collections/{id}/graph`	Get the unified knowledge graph
`POST`	`/api/v1/collections/{id}/answer`	Ask a question grounded in the collection
`POST`	`/api/v1/collections/{id}/qa-verify`	Verify existing Q&A pairs

POST /api/v1/collections

Create a new collection (brand corpus).

Request Body

string

required

Collection name, e.g. "Hyundai UK".

string

Optional URL-friendly identifier, e.g. "hyundai-uk".

cURL

curl -X POST "https://api.factagora.com/api/v1/collections/{id}/answer" \
  -H "Authorization: Bearer fa_your_personal_token" \
  -H "Content-Type: application/json" \
  -d '{"question": "What is the IONIQ 6 electric range?"}'

Python

import requests

resp = requests.post(
    f"https://api.factagora.com/api/v1/collections/{collection_id}/answer",
    headers={"Authorization": "Bearer fa_your_personal_token"},
    json={"question": "What is the IONIQ 6 electric range?"},
)
data = resp.json()

TypeScript

const resp = await fetch(
  `https://api.factagora.com/api/v1/collections/${collectionId}/answer`,
  {
    method: "POST",
    headers: {
      Authorization: "Bearer fa_your_personal_token",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ question: "What is the IONIQ 6 electric range?" }),
  },
);
const data = await resp.json();

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

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

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

string

required

The question to answer.

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 fa_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:

Verdict	Meaning
`correct`	The answer is supported by the collection’s knowledge
`incorrect`	The answer contradicts the knowledge, so a `correction` is provided
`unsupported`	The collection does not have enough information to verify

Request Body

array

required

Array of question/answer pairs to verify (1–50).

Show qa_pairs fields

string

required

The question

string

required

The answer to verify

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 fa_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
  }
}

Overview

Endpoints

Best Practices

Endpoints

POST /api/v1/collections

Request Body

GET /api/v1/collections

GET /api/v1/collections/

DELETE /api/v1/collections/

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//answer

Request Body

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

Request Body

​Endpoints

​POST /api/v1/collections

​Request Body

​GET /api/v1/collections

​GET /api/v1/collections/

​DELETE /api/v1/collections/

​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//answer

​Request Body

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

​Request Body

Endpoints

POST /api/v1/collections

Request Body

GET /api/v1/collections

GET /api/v1/collections/

DELETE /api/v1/collections/

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//answer

Request Body

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

Request Body