# Docmost Bridge — API-Dokumentation

**Version:** 2.4.0
**Base URL:** `https://bridge.addonware.de`

Die Docmost Bridge ist ein schlanker HTTP-Proxy, der den kontrollierten, lesenden und schreibenden Zugriff auf das Docmost-Wissenssystem ermöglicht. Sie abstrahiert die interne Docmost-API und schützt sie durch API-Key-Authentifizierung.

---

## Authentifizierung

Alle Endpunkte (außer `/health`) erfordern einen gültigen API-Key im `Authorization`-Header:

```
Authorization: Bearer <API_KEY>
```

Bei ungültigem Key antwortet die Bridge mit `403 Forbidden`.

---

## Endpunkte

## GET /health

Prüft ob die Bridge läuft. Kein API-Key erforderlich.

**Response**
```json
{
  "status": "ok",
  "version": "2.4.0"
}
```

---

## GET /spaces

Listet alle Spaces auf, auf die der Docmost-Account Zugriff hat.

**Response**
```json
{
  "spaces": [
    {
      "id": "019bb600-f84b-7487-8b42-69b6e71bb365",
      "name": "Knowledge Base",
      "slug": "knowhow"
    }
  ]
}
```

---

## GET /spaces/{space_id}

Gibt Metadaten eines einzelnen Space zurück.

**Parameter**

| Name | Typ | Beschreibung |
|---|---|---|
| `space_id` | UUID | ID des Space |

**Response**
```json
{
  "id": "019bb600-f84b-7487-8b42-69b6e71bb365",
  "name": "Knowledge Base",
  "slug": "knowhow",
  "description": ""
}
```

---

## GET /spaces/{space_id}/pages

Listet alle Seiten eines Space (ohne gelöschte). Gibt die vollständige Baumstruktur zurück, inklusive `parentPageId` und `hasChildren`.

**Parameter**

| Name | Typ | Beschreibung |
|---|---|---|
| `space_id` | UUID | ID des Space |

**Response**
```json
{
  "data": {
    "items": [
      {
        "id": "019ca0f5-1370-747b-98b4-a53ba3f8ab2e",
        "title": "Checkliste: Backup & Restore-Routine",
        "icon": null,
        "position": 1,
        "parentPageId": "019ca0f5-0be5-76f2-be8d-834f4e8e4848",
        "spaceId": "019bb600-f84b-7487-8b42-69b6e71bb365",
        "hasChildren": false
      }
    ]
  }
}
```

---

## GET /pages/{page_id}

Gibt den vollständigen Inhalt einer einzelnen Seite zurück, inklusive TipTap-JSON.

**Parameter**

| Name | Typ | Beschreibung |
|---|---|---|
| `page_id` | UUID | ID der Seite |

**Response**
```json
{
  "data": {
    "id": "019ca0f5-1370-747b-98b4-a53ba3f8ab2e",
    "title": "Checkliste: Backup & Restore-Routine",
    "content": { "type": "doc", "content": [...] },
    "spaceId": "019bb600-f84b-7487-8b42-69b6e71bb365",
    "createdAt": "2026-02-27T21:15:41.806Z",
    "updatedAt": "2026-02-27T21:19:46.844Z"
  }
}
```

---

## GET|POST /search

Volltextsuche über alle Seiten. Unterstützt sowohl GET (Query-Parameter) als auch POST (JSON-Body).

**GET — Query-Parameter**

| Name | Typ | Beschreibung |
|---|---|---|
| `q` oder `keyword` | string | Suchbegriff |
| `space_id` | UUID | Optional: Suche auf einen Space einschränken |

**Beispiel GET**
```
GET /search?q=backup&space_id=019bb600-f84b-7487-8b42-69b6e71bb365
```

**POST — JSON-Body**

```json
{
  "q": "backup",
  "space_id": "019bb600-f84b-7487-8b42-69b6e71bb365"
}
```

**Response**
```json
{
  "data": {
    "items": [
      {
        "id": "019ca0f5-1370-747b-98b4-a53ba3f8ab2e",
        "title": "Checkliste: Backup & Restore-Routine",
        "rank": 1.060495,
        "highlight": "Pr\u00fcfung und quartalsweiser Restore-<b>Test</b>",
        "space": {
          "id": "019bb600-f84b-7487-8b42-69b6e71bb365",
          "name": "Knowledge Base",
          "slug": "knowhow"
        }
      }
    ]
  },
  "success": true,
  "status": 200
}
```

---

## POST /pages

Legt eine neue Seite an. Mit `content` wird Markdown importiert und direkt als TipTap-Dokument gespeichert.

**JSON-Body**

| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| `title` | string | ✅ | Seitentitel |
| `space_id` | UUID | ✅ | Ziel-Space |
| `content` | string | — | Markdown-Inhalt |
| `parent_page_id` | UUID | — | Übergeordnete Seite |

**Beispiel**
```json
{
  "title": "Neue Checkliste",
  "space_id": "019bb600-f84b-7487-8b42-69b6e71bb365",
  "parent_page_id": "019ca0f5-0be5-76f2-be8d-834f4e8e4848",
  "content": "# Neue Checkliste\n\nInhalt hier..."
}
```

**Response:** Die neu erstellte Seite als JSON-Objekt.

---

## PATCH /pages/{page_id}

Aktualisiert Titel und/oder Inhalt einer bestehenden Seite.

**Parameter**

| Name | Typ | Beschreibung |
|---|---|---|
| `page_id` | UUID | ID der zu aktualisierenden Seite |

**JSON-Body**

| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| `title` | string | — | Neuer Titel |
| `content` | string | — | Neuer Inhalt als Markdown |

**Beispiel**
```json
{
  "title": "Aktualisierter Titel",
  "content": "# Aktualisierter Inhalt\n\nNeuer Text..."
}
```

**Response**
```json
{
  "status": "updated",
  "pageId": "019ca0f5-1370-747b-98b4-a53ba3f8ab2e"
}
```

---

## Bekannte Space-IDs

| Space | ID |
|---|---|
| Knowledge Base | `019bb600-f84b-7487-8b42-69b6e71bb365` |
| OpenSpace | `019bd4d2-2d7c-75f4-93c5-aa2da71f0fd8` |
| Förderprogramme | `019b6122-ded3-7e98-8f17-ba8455e1653a` |

---

## Fehlercodes

| Code | Bedeutung |
|---|---|
| `403` | Ungültiger oder fehlender API-Key |
| `404` | Seite oder Ressource nicht gefunden |
| `405` | HTTP-Methode nicht erlaubt |
| `502` | Docmost intern nicht erreichbar |

---

## Curl-Beispiele

**Health Check**
```bash
curl -s https://bridge.addonware.de/health
```

**Seiten eines Space laden**
```bash
curl -s https://bridge.addonware.de/spaces/019bb600-f84b-7487-8b42-69b6e71bb365/pages \
  -H "Authorization: Bearer <API_KEY>" | python3 -m json.tool
```

**Suche**
```bash
curl -s -X POST https://bridge.addonware.de/search \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"q": "backup"}' | python3 -m json.tool
```

**Seite anlegen**
```bash
curl -s -X POST https://bridge.addonware.de/pages \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Neue Seite",
    "space_id": "019bb600-f84b-7487-8b42-69b6e71bb365",
    "content": "# Neue Seite\n\nInhalt hier."
  }' | python3 -m json.tool
```

**Seite aktualisieren**
```bash
curl -s -X PATCH https://bridge.addonware.de/pages/<PAGE_ID> \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"content": "# Aktualisiert\n\nNeuer Inhalt."}' | python3 -m json.tool
```