# Cubicle API

> Die REST-API für deutsches Recht. 116.000+ kuratierte Quellen, DSGVO-konform, EU-gehostet.

**Base-URL:** `https://api.cubicle.legal/v1/knowledge`
**OpenAPI:** [openapi.yaml](https://api.cubicle.legal/v1/knowledge/openapi.yaml)
**Support:** support@cubicle.legal

---

## 🚀 Quick Start

### 1. Account anlegen
```
https://cubicle.legal/api/signup
```
Anmelden, API-Key bekommen, loslegen. Rechnung folgt per E-Mail.

### 2. API-Key generieren
Im Dashboard unter „API Keys" → „Create Key". Format: `cub_<prefix>_<secret>`.
**Wichtig:** Key wird nur **einmal** angezeigt — sicher aufbewahren.

### 3. Erste Anfrage

```bash
curl https://api.cubicle.legal/v1/knowledge/search \
  -H "Authorization: Bearer cub_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Schonfristzahlung Mietrecht",
    "branch": "kanzlei",
    "topK": 5
  }'
```

---

## 📚 Endpoints

### `GET /branches`
Liste verfügbarer Branchen + Anzahl indizierter Dokumente.

```bash
curl https://api.cubicle.legal/v1/knowledge/branches \
  -H "Authorization: Bearer cub_YOUR_KEY"
```

**Response:**
```json
{
  "branches": [
    { "slug": "kanzlei", "name": "Kanzlei / Rechtsanwalt", "doc_count": 93770 },
    { "slug": "steuerberater", "name": "Steuerberater", "doc_count": 14418 },
    { "slug": "wirtschaftspruefer", "name": "Wirtschaftsprüfer", "doc_count": 2863 }
  ]
}
```

### `POST /search`
RAG-Suche in einer Branche. Liefert die relevantesten Treffer mit Snippet, Quelle und Score.

```bash
curl https://api.cubicle.legal/v1/knowledge/search \
  -H "Authorization: Bearer cub_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "§ 535 BGB Mietverhaeltnis",
    "branch": "kanzlei",
    "topK": 3
  }'
```

**Request-Body:**
| Feld | Typ | Default | Beschreibung |
|---|---|---|---|
| `query` | string (2-2000) | — | Suchbegriff oder Paragraphen-Referenz |
| `branch` | enum | `kanzlei` | `kanzlei` / `steuerberater` / `wirtschaftspruefer` / `hotel` / `agentur` |
| `topK` | int (1-50) | 5 | Anzahl Treffer |
| `filters.type` | array | — | Filter nach Typ: `law`, `decision`, `article`, `bmf` |

**Response:**
```json
{
  "results": [
    {
      "type": "law",
      "label": "§ 535 BGB",
      "snippet": "Durch den Mietvertrag wird der Vermieter verpflichtet...",
      "source": "BGB",
      "sections": ["§ 535"],
      "aktenzeichen": null,
      "court": null,
      "score": 0.92
    }
  ],
  "query_id": "6e8f9c3d-fb7c-4e16-9db4-cf55b00ca265",
  "usage": {
    "month_queries": 47,
    "tier_limit": 10000,
    "remaining": 9953
  }
}
```

### `GET /usage`
Aktuelle Verbrauchszahlen + Plan-Info.

```bash
curl https://api.cubicle.legal/v1/knowledge/usage \
  -H "Authorization: Bearer cub_YOUR_KEY"
```

**Response:**
```json
{
  "client": {
    "id": "ea05de57-...",
    "name": "Kanzlei Mueller GmbH",
    "plan": "professional",
    "plan_price_eur": 199
  },
  "current_month": "2026-05",
  "search": {
    "queries_used": 47,
    "tier_limit": 10000,
    "remaining": 9953,
    "reset_date": "2026-06-01"
  },
  "upgrade_url": "https://cubicle.legal/api/upgrade"
}
```

---

## 💰 Pricing

| Plan | Preis/Monat | Queries/Monat | Support | Mindestlaufzeit |
|---|---|---|---|---|
| **Standard** | **99 €** | **10.000** | E-Mail (24h) | monatlich kündbar |
| Enterprise | individuell | > 100.000 | 24/7 + Account-Manager | individuell |

**Alle Preise zzgl. MwSt.**

Upgrade jederzeit: https://cubicle.legal/api/upgrade

---

## 🔒 DSGVO + Datenschutz

- **Standort:** Zertifiziertes Rechenzentrum in Deutschland
- **AVV:** Verfügbar auf Anfrage (kostenlos)
- **Verschlüsselung:** LUKS-AES-256 at-rest, TLS 1.3 in transit
- **Keine LLM-Tracing:** Anfragen werden nicht an Dritte gesendet, kein Anthropic/OpenAI-Logging
- **Audit-Log:** Verfügbar für Enterprise-Kunden
- **Sub-Verarbeiter:** Deutscher Cloud-Anbieter (Details im AVV)

Datenschutz-Fragen: privacy@cubicle.legal

---

## ⚙️ SDK-Beispiele

### JavaScript / TypeScript

```typescript
const apiKey = process.env.CUBICLE_API_KEY!;

async function searchLaw(query: string) {
  const res = await fetch('https://api.cubicle.legal/v1/knowledge/search', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ query, branch: 'kanzlei', topK: 5 }),
  });
  return res.json();
}
```

### Python

```python
import requests, os

API_KEY = os.environ['CUBICLE_API_KEY']

def search_law(query: str):
    return requests.post(
        'https://api.cubicle.legal/v1/knowledge/search',
        headers={'Authorization': f'Bearer {API_KEY}'},
        json={'query': query, 'branch': 'kanzlei', 'topK': 5}
    ).json()
```

### PHP

```php
$apiKey = getenv('CUBICLE_API_KEY');

function searchLaw(string $query): array {
    global $apiKey;
    $ctx = stream_context_create([
        'http' => [
            'method'  => 'POST',
            'header'  => "Authorization: Bearer $apiKey\r\nContent-Type: application/json\r\n",
            'content' => json_encode(['query' => $query, 'branch' => 'kanzlei', 'topK' => 5]),
        ],
    ]);
    return json_decode(file_get_contents('https://api.cubicle.legal/v1/knowledge/search', false, $ctx), true);
}
```

---

## 🔧 Rate-Limiting

Wenn das Monatslimit erreicht ist: HTTP 429 mit Body:

```json
{
  "error": "Monthly limit of 1000 reached. Upgrade plan or wait until 2026-06-01.",
  "used": 1000,
  "limit": 1000,
  "reset_date": "2026-06-01"
}
```

→ Plan upgraden oder bis Monatsanfang warten.

---

## 🐛 Fehler-Codes

| Code | Bedeutung | Lösung |
|---|---|---|
| 400 | Validation Error | Body prüfen (query, branch, topK) |
| 401 | Invalid API Key | Token prüfen, ggf. neu erstellen |
| 403 | Account inactive | Support kontaktieren |
| 429 | Rate-Limit erreicht | Plan upgraden |
| 500 | Server-Fehler | Bei wiederholtem Auftreten: support@cubicle.legal |

---

## 📞 Support

- **E-Mail:** support@cubicle.legal
- **Docs:** https://api.cubicle.legal/docs
- **Status:** https://status.cubicle.legal
- **GitHub Issues:** github.com/cubicle-legal/api/issues

---

*Cubicle API — die deutsche Rechts-API. © 2026 Cubicle GmbH.*