REST API¶

The FastAPI backend exposes a REST API for all document ingestion, search, and AI query operations.

Base URL: http://localhost:8000/api/

Interactive API Documentation¶

Both UIs are served by the running backend and let you try every endpoint directly in the browser.

Endpoints¶

System¶

Ingestion¶

All three text ingestion endpoints (/api/ingest, /api/ingest-text, /api/test-sample) accept enabled_graph and enabled_rdf booleans: which graphs to build, the property graph (PG_GRAPH_DB) and the RDF graph (RDF_GRAPH_DB), each on its own. One not given follows the server's DEFAULT_ENABLED_GRAPH / DEFAULT_ENABLED_RDF (both true unless set). The older skip_graph boolean still works: it skips KG extraction and all graph writes — vector and full-text stores are still updated. GET /api/ui-defaults returns those defaults, plus recursive (DEFAULT_RECURSIVE, where the UIs' Deep checkbox starts) and show_graph / show_rdf (whether a graph store is configured with ENABLE_KNOWLEDGE_GRAPH on). See the auto-sync API reference for ingest status, removal and per-row runs.

Async Processing¶

Search & Query¶

Both take optional source_auth (the asker's sign-ins, per source: alfresco, nuxeo, cmis, microsoft, box, google, azure, s3) to return only documents that user may read, and sources (a list of {source, url?}) to limit the question to chosen sources.

Sign-In¶

See the Sign-In and Permission-Aware Search guide.

Graph¶

POST /api/graph/query routes to the appropriate query language automatically based on the configured graph backend:

Request body:

{
  "query": "MATCH (p:Person)-[:WORKS_FOR]->(c:Company) RETURN p.name, c.name LIMIT 10",
  "language": "cypher",
  "params": {}
}

The language field is optional — the backend infers it from the configured store when omitted.

RDF / Ontology¶

These endpoints are active when RDF_GRAPH_DB is set to fuseki, graphdb, oxigraph, or neptune_rdf.

Example Requests¶

Health Check¶

curl http://localhost:8000/api/health

Ingest from Filesystem (folder)¶

curl -X POST http://localhost:8000/api/ingest \
  -H "Content-Type: application/json" \
  -d '{
    "data_source": "filesystem",
    "config": {"path": "/path/to/docs"},
    "skip_graph": false
  }'

Upload a File¶

curl -X POST http://localhost:8000/api/upload \
  -F "files=@/path/to/document.pdf"

Ingest Text Directly¶

curl -X POST http://localhost:8000/api/ingest-text \
  -H "Content-Type: application/json" \
  -d '{"content": "Acme Corp was founded in 2010 by John Smith.", "source_name": "company-info"}'

Hybrid Search¶

curl -X POST http://localhost:8000/api/search \
  -H "Content-Type: application/json" \
  -d '{"query": "knowledge graph extraction", "top_k": 5}'

AI Q&A Query¶

curl -X POST http://localhost:8000/api/query \
  -H "Content-Type: application/json" \
  -d '{"query": "What are the main topics in the documents?", "top_k": 10}'

Poll Processing Status¶

# Get the task ID from an async ingest response, then poll:
curl http://localhost:8000/api/processing-status/{task_id}

# Or stream real-time events:
curl -N http://localhost:8000/api/processing-events/{task_id}

Native Graph Query (Cypher — Neo4j)¶

curl -X POST http://localhost:8000/api/graph/query \
  -H "Content-Type: application/json" \
  -d '{"query": "MATCH (p:Person)-[:WORKS_FOR]->(c:Company) RETURN p.name, c.name LIMIT 10"}'

Native Graph Query (AQL — ArangoDB)¶

curl -X POST http://localhost:8000/api/graph/query \
  -H "Content-Type: application/json" \
  -d '{"query": "FOR v IN Person FILTER LOWER(v.name) CONTAINS \"acme\" RETURN v.name", "language": "aql"}'

SPARQL Query (RDF store)¶

curl -X POST http://localhost:8000/api/rdf/query/sparql \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10"}'

Async Ingestion Flow¶

Long-running ingestion operations (large files, many documents) return a task_id immediately:

POST /api/ingest  →  { "task_id": "abc123", "status": "processing" }
GET /api/processing-status/abc123  →  { "status": "running", "progress": 42 }
GET /api/processing-events/abc123  →  SSE stream with real-time progress updates
POST /api/cancel-processing/abc123  →  cancel if needed

CocoIndex endpoints¶

When PIPELINE_BACKEND=cocoindex, additional endpoints (/api/cocoindex/status, /api/cocoindex/sync-now, /api/cocoindex/config) are available. See CocoIndex Developer Guide — Running and driving it.

See Also¶

• Architecture — detailed API workflow and data flow diagrams
• MCP Server — higher-level tools built on top of these endpoints
• RDF Store User Guide — RDF/SPARQL endpoint details
• CocoIndex Developer Guide — CocoIndex CLI vs FastAPI, custom pipelines