docs/API.md

Knowledge Universe API — Reference

Base URL: https://knowledge-universe.onrender.com
(or your custom domain once configured)

Authentication

All endpoints except /v1/signup, /v1/formats, /v1/crawlers, /health require an API key.

X-API-Key: ku_test_your_key_here

Signup — Get a free key

curl -X POST "https://knowledge-universe.onrender.com/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."
}

POST /v1/discover

Discover sources across 13 platforms. Returns decay score on every result.

curl -X POST https://knowledge-universe.onrender.com/v1/discover \
  -H "X-API-Key: ku_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "transformer architecture",
    "difficulty": 3,
    "formats": ["pdf", "github", "stackoverflow"],
    "max_results": 10
  }'

Request body

Field	Type	Required	Description
topic	string	✓	Search query (2–200 chars)
difficulty	int 1–5	✓	1=beginner, 5=research
formats	string[]	—	Default: pdf, video, github, jupyter
max_results	int 1–50	—	Default: 10
output	string	—	json | embeddings (default: json)

Response

{
  "query": "transformer architecture",
  "total_found": 8,
  "credits_used": 1,
  "credits_remaining": 499,
  "cache_hit": false,
  "processing_time_ms": 3944.5,
  "decay_scores": {
    "arxiv:1706.03762": {
      "decay_score": 0.847,
      "freshness": 0.153,
      "label": "stale",
      "age_days": 2736
    }
  },
  "coverage_intelligence": {
    "confidence": 0.71,
    "confidence_label": "high",
    "coverage_warning": false,
    "suggested_queries": []
  },
  "sources": [...]
}

Decay labels: fresh (< 0.25) · aging (0.25–0.50) · stale (0.50–0.75) · decayed (> 0.75)

GET /v1/usage

curl https://knowledge-universe.onrender.com/v1/usage -H "X-API-Key: ku_test_..."

POST /v1/knowledge

Enterprise: Returns KnowledgeObjects with optional 384-dim embeddings. Set "output": "embeddings" for vectors compatible with Qdrant, Weaviate, ChromaDB, Pinecone.

GET /v1/formats

All 54 supported source formats. No auth.

Error Codes

Code	HTTP	Fix
MISSING_API_KEY	401	Add X-API-Key header
INVALID_API_KEY	401	Check key, re-signup if lost
EMAIL_EXISTS	409	Use different email
QUOTA_EXCEEDED	429	Upgrade plan or wait for reset
INTERNAL_ERROR	500	Retry; open GitHub issue if persists