Spaces:
Running
Running
File size: 2,755 Bytes
b32fbe0 5979c41 b32fbe0 5979c41 b32fbe0 5979c41 b32fbe0 5979c41 b32fbe0 5979c41 b32fbe0 5979c41 b32fbe0 5979c41 b32fbe0 5979c41 b32fbe0 5979c41 b32fbe0 5979c41 b32fbe0 5979c41 b32fbe0 5979c41 b32fbe0 5979c41 b32fbe0 5979c41 b32fbe0 5979c41 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 | # 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
```bash
curl -X POST "https://knowledge-universe.onrender.com/v1/signup?email=you@company.com"
```
Response:
```json
{
"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.
```bash
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
```json
{
"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
```bash
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 | |