Knowledge Universe — API Documentation

Quickstart

Get your first result in under 60 seconds. No credit card. No OAuth flow.

Step 1 — Get a free API key

bash

curl -X POST "https://api.knowledgeuniverse.tech/v1/signup?email=you@company.com"

response

{
  "status": "created",
  "api_key": "ku_test_abc123...",
  "tier": "free",
  "calls_limit": 500,
  "message": "Save your API key — it won't be shown again."
}

⚠ Save your key immediately

Your API key is shown exactly once. It is not stored in plain text. If lost, sign up again with a different email.

Step 2 — Discover sources

bash

curl -X POST https://api.knowledgeuniverse.tech/v1/discover \
  -H "X-API-Key: ku_test_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"topic":"transformer architecture","difficulty":3,"formats":["pdf","github"]}'

Step 3 — Read the decay scores

response (excerpt)

{
  "max_decay_detected": 0.711,
  "decay_scores": {
    "arxiv:2302.14017v1": {
      "decay_score": 0.504,
      "freshness": 0.496,
      "label": "stale",
      "age_days": 1107,
      "days_until_stale": 0
    }
  },
  "knowledge_velocity": {
    "velocity_label": "hypersonic",
    "median_age_days": 36,
    "pct_from_last_90_days": 1.0
  },
  "coverage_intelligence": {
    "confidence": 0.71,
    "confidence_label": "high",
    "coverage_warning": false
  }
}

Authentication

Pass your API key in the X-API-Key header on every authenticated call.

bash

curl https://api.knowledgeuniverse.tech/v1/usage \
  -H "X-API-Key: ku_test_abc123..."

python

import requests

resp = requests.post(
    "https://api.knowledgeuniverse.tech/v1/discover",
    headers={"X-API-Key": "ku_test_abc123..."},
    json={"topic": "RAG retrieval", "difficulty": 3},
)
data = resp.json()

Key Formats

Prefix	Tier	Monthly limit
`ku_test_`	Free	500 calls
`ku_live_`	Starter / Growth / Pro / Enterprise	5k – unlimited

Key rotation

Keys do not expire on a time basis. Usage resets on the 1st of every month UTC. To upgrade your tier, subscribe on the pricing page and email your receipt to vlsiddarth7@gmail.com — your key will be upgraded within 2 hours.

Error Codes

HTTP	Error code	Meaning	Fix
`401`	`MISSING_API_KEY`	No key in header	Add X-API-Key` header
`401`	`INVALID_API_KEY`	Key not found	Check for typos; re-signup if lost
`409`	`EMAIL_EXISTS`	Already registered	Use a different email
`422`	Validation error	Bad request body	Check required fields
`429`	`QUOTA_EXCEEDED`	Monthly limit hit	Upgrade or wait for reset
`500`	`INTERNAL_ERROR`	Server fault	Retry; open a GitHub issue if persists

POST /v1/signup

Create a free account and receive your API key. No authentication required.

POST https://api.knowledgeuniverse.tech/v1/signup

Query parameters

Param	Type	Required	Description
`email`	string	required	Your email address. Used as unique account identifier.
`tier`	string	optional	Default: `free`.

bash

curl -X POST "https://api.knowledgeuniverse.tech/v1/signup?email=you@company.com"

POST /v1/discover

The core endpoint. Queries 14+ platforms in parallel, scores quality and freshness, attaches a deterministic decay score and coverage confidence to every response.

POST https://api.knowledgeuniverse.tech/v1/discover

Request body

Field	Type		Description
`topic`	string	required	Search query. 2–200 characters.
`difficulty`	int 1–5	required	1 = beginner, 5 = research-level.
`formats`	string[]	optional	Filter by format. Default: all formats.
`max_results`	int 1–50	optional	Default: `10`
`output`	string	optional	`json` \| `embeddings` \| `html`

Response fields (key)

Field	Type	Description
`max_decay_detected`	float	Highest decay score in the returned set. Gate on this for hard-blocking.
`decay_scores`	object	Per-source decay_score, freshness, label, age_days, days_until_stale.
`knowledge_velocity`	object	Domain velocity label: frozen / slow / moderate / fast / hypersonic.
`conflict_detection`	object	conflicts_found count and conflict_pairs array.
`coverage_intelligence`	object	Confidence score + suggested_queries if coverage is low.

bash

curl -X POST https://api.knowledgeuniverse.tech/v1/discover \
  -H "X-API-Key: ku_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "FDA clinical trial adverse event reporting 2026",
    "difficulty": 4,
    "formats": ["pdf","github"],
    "max_results": 10
  }'

⚡ Caching

Cold queries: ~5–25 seconds (14+ crawlers in parallel). Cache hits: ~220ms. TTL: 4 hours. Same query from any user hits cache immediately.

POST /v1/knowledge

Enterprise endpoint. Returns KnowledgeObjects with freshness scores pre-attached — designed for direct RAG pipeline ingestion.

POST https://api.knowledgeuniverse.tech/v1/knowledge

Same request body as /v1/discover. Set "output": "embeddings" for 384-dim vectors ready for Qdrant, Weaviate, ChromaDB, Pinecone.

bash

curl -X POST https://api.knowledgeuniverse.tech/v1/knowledge \
  -H "X-API-Key: ku_test_..." \
  -H "Content-Type: application/json" \
  -d '{"topic":"RAG retrieval","difficulty":3,"output":"embeddings"}'

GET /v1/usage

Check your current month usage and remaining quota.

GET https://api.knowledgeuniverse.tech/v1/usage

bash

curl https://api.knowledgeuniverse.tech/v1/usage \
  -H "X-API-Key: ku_test_..."

200 response

{
  "tier": "free",
  "calls_used": 4,
  "calls_limit": 500,
  "calls_remaining": 496,
  "reset": "1st of next month"
}

GET /v1/formats

Returns all supported format values. No auth required.

GET https://api.knowledgeuniverse.tech/v1/formats

bash

curl https://api.knowledgeuniverse.tech/v1/formats

GET /v1/crawlers

Lists all registered crawlers and their status. No auth required.

GET https://api.knowledgeuniverse.tech/v1/crawlers

bash

curl https://api.knowledgeuniverse.tech/v1/crawlers

GET /health

Liveness check. Returns Redis status. No auth. Use for uptime monitoring.

GET https://api.knowledgeuniverse.tech/health

200 response

{ "status": "healthy", "version": "1.0.0", "redis": "connected" }

Decay Engine

Every source gets a knowledge decay score — how much its relevance has drifted since publication. This is the core IP of Knowledge Universe.

formula

decay = 1 - 0.5 ^ (age_days / half_life_days)
freshness = 1 - decay

Half-life by platform

Platform	Half-life	Reasoning
HuggingFace	120 days	ML moves extremely fast
GitHub	180 days	Code goes stale as dependencies update
YouTube	270 days	Tutorials date quickly
Stack Overflow	365 days	Answers age with library versions
Kaggle	365 days	Notebooks tied to competition contexts
arXiv	1,095 days	Research papers age slowly
MIT OCW	1,095 days	Course material revised on academic cycles
Wikipedia	1,460 days	Actively maintained
Open Library	1,825 days	Books revised infrequently

Decay labels

fresh

0.00 – 0.25

aging

0.25 – 0.50

stale

0.50 – 0.75

decayed

0.75 – 1.00

unknown

no date

Why this matters for RAG

LLMs and vector stores have no concept of source age. A 2019 Stack Overflow answer and a 2025 answer rank identically in cosine similarity. The decay score lets your pipeline filter or warn before stale knowledge reaches a response. Use max_decay_detected as a single gate threshold — block anything above 0.4 in fast-moving domains.

Coverage Confidence Score

KU is the only retrieval API that tells you when it didn't find exactly what you were looking for. Every /v1/discover response includes a coverage_intelligence field.

Label	Confidence range	Meaning
`high`	≥ 0.65	Results well match your query intent
`medium`	0.45 – 0.65	Partial match — consider refining
`low`	< 0.45	Significant mismatch — try suggested queries
`none`	0.0	No results returned

Source Formats

Pass any combination in the formats array.

Group	Format values
Textual	`html` `pdf` `markdown` `epub` `latex`
Video & Audio	`video` `video_playlist` `transcript` `audio` `podcast`
Interactive & Data	`jupyter` `dataset` `colab` `sandbox`
Code & Repos	`github` `repository` `snippet`
Academic & Q&A	`problem_set` `stackoverflow` `kaggle` `flashcards`

Platforms

Free = no key needed. Keyed = uses your rotating API keys on the backend.

arXiv

Research papers

✓ Free

Wikipedia

Encyclopedia

✓ Free

Open Library

Books / EPUB

✓ Free

Stack Exchange

Q&A

✓ Free

HuggingFace

Models / Datasets

✓ Free

MIT OCW

University courses

✓ Free

Semantic Scholar

Academic citations

✓ Free

GitHub

Repos / Notebooks

⚙ Managed key

YouTube

Video lectures

⚙ Managed key

Kaggle

Notebooks / Datasets

⚙ Managed key

Output Formats

Value	Returns	Use case
`json`	Default JSON response	General use, dashboards
`embeddings`	JSON + 384-dim vectors per source	Direct vector store ingestion
`html`	Formatted HTML cards	Browser rendering, reports

All Endpoints

POST /v1/signup Create account, receive API key no auth

POST /v1/discover Multi-platform discovery + decay scores + velocity + conflict detection auth

POST /v1/knowledge Enterprise KnowledgeObjects + embeddings for vector stores auth

GET /v1/usage Monthly credit usage and remaining calls auth

GET /v1/formats All supported source formats no auth

GET /v1/crawlers Active crawlers and status no auth

GET /health Liveness check, Redis connection status no auth

Rate Limits

Limits are per calendar month, not per minute. To upgrade, see pricing.

Plan	Price	Monthly calls
Free	$0	500
Starter	$29/mo	5,000
Growth	$79/mo	20,000
Pro	$199/mo	75,000
Enterprise	Custom	Unlimited + SLA

Changelog

Version	Date	Changes
`v1.3.0`	May 2026	Production deployment on dedicated domain. `max_decay_detected` as first-class field. Waverunner SKILL.md integration. DigitalOcean production cluster with dedicated Redis.
`v1.2.0`	April 2026	Expanded to 14+ parallel crawlers. Redis ZSET scheduling. Cache hit latency to 220ms. Semantic Scholar integration.
`v1.1.0`	March 2026	Coverage Confidence Score. Per-crawler timeouts. Cold latency 25s → 5s.
`v1.0.0`	March 2026	Initial release. Auth, decay engine, 13 crawlers, /v1/discover, /v1/knowledge.