API Reference

Authentication

Create an API key in Settings and include it in every request:

curl -H "X-API-Key: tc_live_your_key_here" \
     https://app.theconsilience.io/v1/ingest/sources

Or use the Authorization header:

curl -H "Authorization: Bearer tc_live_your_key_here" \
     https://app.theconsilience.io/v1/ingest/sources

Ingest Endpoints

POST /v1/ingest/url

Ingest any URL. Auto-detects arXiv, bioRxiv, DOI, YouTube, and web articles.

curl -X POST https://app.theconsilience.io/v1/ingest/url \
  -H "X-API-Key: tc_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://arxiv.org/abs/2504.02914"}'

POST /v1/ingest/thought

Capture a text thought directly into your knowledge garden.

curl -X POST https://app.theconsilience.io/v1/ingest/thought \
  -H "X-API-Key: tc_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"text": "Your thought or passage here", "topic_slug": "consciousness"}'

POST /v1/ingest/bibtex

Upload a BibTeX file to batch-ingest references.

curl -X POST https://app.theconsilience.io/v1/ingest/bibtex \
  -H "X-API-Key: tc_live_your_key" \
  -F "file=@references.bib"

POST /v1/ingest/doi

Ingest a paper by DOI. Fetches metadata from CrossRef and PDF from Unpaywall.

curl -X POST https://app.theconsilience.io/v1/ingest/doi \
  -H "X-API-Key: tc_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"doi": "10.1016/j.concog.2014.03.012"}'

POST /v1/ingest/voice

Upload an audio file (mp3, wav, m4a, webm). Transcribed via Groq Whisper.

curl -X POST https://app.theconsilience.io/v1/ingest/voice \
  -H "X-API-Key: tc_live_your_key" \
  -F "file=@recording.m4a"

Query Endpoints

GET /v1/search?q=...

Keyword search across sources, captures, generations, vocabulary, and clusters.

curl "https://app.theconsilience.io/v1/search?q=unified+field" \
  -H "X-API-Key: tc_live_your_key"

GET /v1/search/semantic?q=...

Semantic search against the essence embedding namespace. Finds cross-tradition connections.

curl "https://app.theconsilience.io/v1/search/semantic?q=consciousness+as+primary" \
  -H "X-API-Key: tc_live_your_key"

GET /v1/garden/graph

Returns recognition clusters, vocabulary bridges, and source nodes for the knowledge graph.

curl https://app.theconsilience.io/v1/garden/graph \
  -H "X-API-Key: tc_live_your_key"

GET /v1/ingest/sources

List all ingested sources with metadata, chunk counts, and status.

curl https://app.theconsilience.io/v1/ingest/sources \
  -H "X-API-Key: tc_live_your_key"

GET /v1/ingest/confirmations

Get pending vocabulary bridge proposals awaiting your review.

curl https://app.theconsilience.io/v1/ingest/confirmations \
  -H "X-API-Key: tc_live_your_key"

Export

GET /v1/share/export

Download your entire knowledge garden as a ZIP file (sources, vocabulary map, clusters, generations).

GET /v1/share/bibliography?format=bibtex

Export all sources as a bibliography. Formats: bibtex, apa, chicago, mla.

curl -o references.bib \
  "https://app.theconsilience.io/v1/share/bibliography?format=bibtex" \
  -H "X-API-Key: tc_live_your_key"

Webhooks

Receive notifications when events occur in your knowledge garden.

POST /v1/webhooks

Register a webhook URL to receive event notifications.

curl -X POST https://app.theconsilience.io/v1/webhooks \
  -H "X-API-Key: tc_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-server.com/webhook",
       "events": ["ingest.complete", "cluster.crystallised"]}'

Events: ingest.complete, ingest.failed, cluster.crystallised

Webhook payloads include an X-Consilience-Signature header (HMAC-SHA256) for verification.

Python Example

Copy the example script: docs/sdk/python_example.py

pip install httpx

import httpx

API_KEY = "tc_live_your_key"
BASE = "https://app.theconsilience.io"
headers = {"X-API-Key": API_KEY}

# Ingest an arXiv paper
r = httpx.post(f"{BASE}/v1/ingest/url",
    json={"url": "https://arxiv.org/abs/2504.02914"},
    headers=headers)
print(r.json())

# Search your garden
r = httpx.get(f"{BASE}/v1/search",
    params={"q": "consciousness"},
    headers=headers)
print(r.json())

# Get your knowledge graph
r = httpx.get(f"{BASE}/v1/garden/graph",
    headers=headers)
garden = r.json()
print(f"{len(garden['nodes'])} nodes, {len(garden['edges'])} edges")