# API Contract: Clew
**Version:** v1 (Indie)
**Base URL:** `http://localhost:8000/v1`

## Authentication
All requests must include the `Authorization` header.
`Authorization: Bearer <Clew_API_KEY>`

---

## 1. Search (Hybrid)
The main entry point for retrieval. Combines vector similarity with optional graph filtering.

**POST** `/search`

### Request
```json
{
  "query": "How is the user session validated?",
  "limit": 5,
  "repo": "owner/repo-name"
}
```

### Response
```json
{
  "results": [
    {
      "id": "file:auth/session.py",
      "score": 0.89,
      "text": "def validate_session(token): ...",
      "metadata": {
        "path": "auth/session.py",
        "type": "code_chunk",
        "repo": "owner/repo-name"
      }
    }
  ]
}
```

---

## 2. Graph Traversal
Explore the structural relationships around a specific code artifact.

**POST** `/graph/traverse`

### Request
```json
{
  "start_node_id": "file:auth/session.py",
  "relationship_types": ["CALLS", "DEFINES"],
  "depth": 2
}
```

### Response
```json
{
  "nodes": [
    { "id": "func:validate_session", "label": "validate_session", "type": "function" },
    { "id": "class:SessionManager", "label": "SessionManager", "type": "class" }
  ],
  "edges": [
    { "source": "class:SessionManager", "target": "func:validate_session", "type": "DEFINES" }
  ]
}
```
