# Nexus-Plex API – Partner-Dokumentation

**Betreiber:** Aegis Vitae  
**Systemversion:** Nexus-Plex API V0.3.0  
**Basis-URL:** `http://localhost/aegis-nexus-plex/Backend/api/index.php`

---

## 1. Onboarding (neuer Mandant)

Neue Partner erhalten `tenant_id` und `API-Key` über den Onboarding-Endpunkt.

**Endpoint:** `POST /Backend/api/onboarding.php`

**Header:**

| Header | Wert |
|--------|------|
| `Content-Type` | `application/json` |
| `X-Onboarding-Secret` | Vom Betreiber (Aegis Vitae) bereitgestellt |

**Body (JSON):**

```json
{
  "tenant_name": "Mein Partner GmbH",
  "email": "api@partner.de",
  "usage_quota": 5000,
  "plan": "pro"
}
```

**Antwort (201):**

```json
{
  "operator": "Aegis Vitae",
  "api_version": "Nexus-Plex API V0.3.0",
  "success": true,
  "tenant_id": 2,
  "tenant_name": "Mein Partner GmbH",
  "api_key": "nx_…",
  "usage_quota": 5000,
  "auth_headers": {
    "X-Tenant-ID": "2",
    "X-API-Key": "nx_…"
  }
}
```

> **Wichtig:** Der `api_key` wird nur einmalig zurückgegeben. Sicher speichern.

---

## 2. Authentifizierung (alle API-Aufrufe)

Jeder Request an `index.php` benötigt **beide** Header:

| Header | Beschreibung |
|--------|--------------|
| `X-Tenant-ID` | Numerische Mandanten-ID |
| `X-API-Key` | Vom Onboarding erhaltener Schlüssel |

Alternativ: `Authorization: Bearer <api_key>` (zusätzlich weiterhin `X-Tenant-ID` erforderlich).

**Beispiel (cURL):**

```bash
curl -X POST "http://localhost/aegis-nexus-plex/Backend/api/index.php?route=/search" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 1" \
  -H "X-API-Key: nx_IHR_API_KEY" \
  -d "{\"query\": \"RFID checkout retail\"}"
```

---

## 3. Antwort-Header (Branding)

Jede JSON-Antwort enthält:

| HTTP-Header | Wert |
|-------------|------|
| `X-Platform-Operator` | `Aegis Vitae` |
| `X-API-Version` | `Nexus-Plex API V0.3.0` |
| `Content-Type` | `application/json; charset=utf-8` |

Im JSON-Body sind zusätzlich `operator` und `api_version` enthalten.

---

## 4. Mandanten-Isolation

- Jeder Tenant sieht nur **eigene** Blueprints, Projekte und Assets (`tenant_id`).
- **Globale Blueprints** (`is_global = 1`) sind für alle Mandanten lesbar.
- Fremde `tenant_id` in Anfragen werden durch den API-Key abgelehnt.

---

## 5. Quota & Rate-Limiting

- Pro Mandant gilt ein monatliches Limit (`usage_quota` in der `tenants`-Tabelle).
- Bei Überschreitung: **HTTP 429** mit `code: "quota_exceeded"`.
- Aktuellen Verbrauch abfragen: `GET ?route=/usage`

**Beispiel 429:**

```json
{
  "operator": "Aegis Vitae",
  "api_version": "Nexus-Plex API V0.3.0",
  "error": "Monatliches API-Limit erreicht (5000/5000 Anfragen).",
  "code": "quota_exceeded",
  "usage": {
    "used": 5000,
    "quota": 5000,
    "remaining": 0,
    "period": "2026-06"
  }
}
```

Alle Anfragen werden in `tenant_usage_logs` protokolliert (Endpoint, Methode, Status, Dauer).

---

## 6. Endpunkte

Routing über Query-Parameter `?route=/…` oder `PATH_INFO`.

| Methode | Route | Beschreibung |
|---------|-------|--------------|
| `GET` | `/status` | System- & Tenant-Status inkl. Usage |
| `GET` | `/usage` | Monatliches Quota |
| `POST` | `/search` | Blueprint-Suche (`query`) |
| `POST` | `/crawl` | URL crawlen (`url`, optional `share_global`) |
| `POST` | `/synthesize` | Komponenten-Synthese |
| `POST` | `/research` | Innovations-Recherche (`problem`, optional `title`) |
| `GET` | `/project-blueprints` | Projekt-Blueprints des Tenants |
| `GET` | `/presentations` | Investoren-Decks |
| `POST` | `/generate-presentation` | Deck generieren (`project_id`) |
| `GET` | `/assets` | Aegis Standard-Assets |
| `POST` | `/adopt-asset` | Modul übernehmen |
| `GET` | `/export-asset` | Asset exportieren (`code`) |
| `POST` | `/import-asset` | Partner-Paket importieren |
| `GET` | `/career` | Karriere-Status (`revenue`) |
| `GET` | `/crawl-status` | Crawl-Warteschlange |

---

## 7. Fehlercodes

| HTTP | Bedeutung |
|------|-----------|
| `400` | Ungültige Anfrage |
| `401` | Auth fehlgeschlagen (Tenant-ID / API-Key) |
| `403` | Onboarding-Secret ungültig |
| `404` | Endpoint oder Ressource nicht gefunden |
| `429` | Monatliches Quota überschritten |
| `500` | Interner Serverfehler |

---

## 8. Demo-Tenant (Entwicklung)

| Feld | Wert |
|------|------|
| `tenant_id` | `1` |
| E-Mail | `martick61@gmail.com` |
| API-Key | Siehe lokale Konfiguration / Admin-Board |

---

*Aegis Vitae · Nexus-Plex – KI-native Innovationsplattform*