# NSCT — API-Referenz

> **Hinweis:** Diese API-Referenz beschreibt nur die Endpunkte
> von Stage 0. Die eigentliche Evidence-Pipeline (Suche,
> Analyse, Report) wird in späteren Stages implementiert.

## Server-Adresse

```
http://localhost:8080
```

Nach `docker compose up`.

---

## System-Endpunkte

### GET /health

**Beschreibung:** Basic health check — gibt den Status und die Version zurück.
Wird von Docker Healthchecks und Load Balancern verwendet.

**Request:**
```
GET /health
```

**Response (200 OK):**
```json
{
  "status": "ok",
  "version": "0.1.0"
}
```

---

### GET /ready

**Beschreibung:** Readiness check — prüft die Erreichbarkeit von
Downstream-Services (LLM-Provider, ggf. Datenbank).

**Request:**
```
GET /ready
```

**Response (200 OK):**

Wenn bereit:
```json
{
  "status": "ready",
  "llm": "ok",
  "database": "unknown",
  "llm_model": "Qwen3.6-6-35B"
}
```

Wenn nicht bereit:
```json
{
  "status": "not_ready",
  "llm": "error:Connection refused",
  "database": "unknown"
}
```

**Mögliche `status`-Werte:**
- `ready` — Alle geprüften Services sind erreichbar
- `not_ready` — Mindestens ein Service ist nicht erreichbar

**Mögliche `llm`-Werte:**
- `ok` — LLM-Provider ist erreichbar
- `error:<detail>` — Fehlerbeschreibung (HTTP-Statuscode oder Exception-Typ)

---

### GET /providers

**Beschreibung:** Listet die konfigurierten Provider ohne Secrets.

**Request:**
```
GET /providers
```

**Response (200 OK):**
```json
{
  "llm": {
    "available": true,
    "model": "Qwen3.6-6-35B",
    "max_concurrency": 3
  },
  "vision": {
    "available": true,
    "model": "Qwen2-VL-3B"
  },
  "audio": {
    "available": true,
    "model": "default"
  }
}
```

**Falls kein Provider konfiguriert:**
```json
{
  "llm": { "available": false },
  "vision": { "available": false },
  "audio": { "available": false }
}
```

**Wichtig:** Dieser Endpoint gibt **keinerlei** Secrets, API-Keys
oder senssible Konfigurationswerte zurück.

---

## Entwicklung (nur mit NSCT_DEBUG=true)

### GET /docs

Swagger UI mit interaktiver API-Documentation.

```bash
curl http://localhost:8080/docs
```

### GET /redoc

ReDoc-Generierung.

```bash
curl http://localhost:8080/redoc
```

---

## Error Response Format

Alle Fehler folgen einem konsistenten Format:

```json
{
  "detail": "Fehlerbeschreibung"
}
```

---

## Authentifizierung

Stage 0: Keine Authentifizierung. Dies wird in späteren Stages
hinzugefügt (API-Key, OAuth, etc.).