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

```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 |