eLibrary API

Die eLibrary API verwaltet eine Dokumenten-Bibliothek: Documents (Metadaten), Collections, Categories und Tags, mit Archive-Funktion und Batch-Anlage. Die eigentlichen Dateien laufen über das zentrale Anhang-System (Entity-Type ELIBRARY_DOCUMENT) — inkl. ClamAV-Scan.

📚

Funktionen

✓ Dateien über das Anhang-System (ELIBRARY_DOCUMENT)

✓ Collections für zusammengehörige Dokumente

✓ Batch-Anlage (bis zu 20 Dokumente)

✓ Kategorien nach Themen

✓ Freie Tags für die Suche

✓ Archivieren statt Löschen

✓ 8 Dokumenttypen (PDF, VIDEO, …)

✓ Volltextsuche (Titel und Publisher)

✓ 7 eigene Rechte (elibrary.*)

✓ Uploader-Tracking (uploadedBy, uploadedAt)

Endpoints Übersicht

Documents

Method	Endpoint	Beschreibung
`GET`	`/api/elibrary/documents`	Alle Documents abrufen (mit Filtering)
`GET`	`/api/elibrary/documents/grouped`	Gruppierte Ansicht (Collections + Standalone)
`GET`	`/api/elibrary/documents/:id`	Einzelnes Document abrufen
`POST`	`/api/elibrary/documents`	Document anlegen (NUR Metadaten, JSON) — Datei separat hochladen
`POST`	`/api/elibrary/documents/batch`	Batch-Anlage (Metadaten + optional Collection), liefert Document-IDs
`PUT`	`/api/elibrary/documents/:id`	Document-Metadata aktualisieren (Uploader oder editAll)
`PATCH`	`/api/elibrary/documents/:id/archive`	Archivieren/Unarchivieren
`DELETE`	`/api/elibrary/documents/:id`	Dokument löschen (die zugehörige Datei wird als gelöscht markiert)

Dateien: Die Datei eines Dokuments wird über das zentrale Anhang-System verwaltet — Upload via POST /api/attachments/ELIBRARY_DOCUMENT/:documentId, Download via GET /api/attachments/:attachmentId/download (inkl. ClamAV-Scan, scanStatus, Quarantäne). Ablauf: erst Document-Metadaten anlegen → dann Datei zum erhaltenen documentId hochladen. Attachments API →

Collections

Method	Endpoint	Beschreibung
`GET`	`/api/elibrary/collections`	Alle Collections abrufen
`GET`	`/api/elibrary/collections/:id`	Einzelne Collection (mit Documents)
`POST`	`/api/elibrary/collections`	Collection erstellen
`PUT`	`/api/elibrary/collections/:id`	Collection aktualisieren
`PATCH`	`/api/elibrary/collections/:id/archive`	Collection archivieren/unarchivieren
`DELETE`	`/api/elibrary/collections/:id`	Collection löschen
`POST`	`/api/elibrary/collections/:id/documents`	Dokumente zu Collection hinzufügen
`POST`	`/api/elibrary/collections/:id/documents/remove`	Dokumente aus Collection entfernen

Categories & Tags

Method	Endpoint	Beschreibung
`GET`	`/api/elibrary/categories`	Alle Categories abrufen
`GET`	`/api/elibrary/categories/:id`	Einzelne Category abrufen
`POST`	`/api/elibrary/categories`	Category erstellen
`PUT`	`/api/elibrary/categories/:id`	Category aktualisieren
`DELETE`	`/api/elibrary/categories/:id`	Category löschen
`GET`	`/api/elibrary/tags`	Alle Tags abrufen

Document-Types

Type	Beschreibung
`PDF`	PDF-Dokumente
`EBOOK`	E-Books
`WHITEPAPER`	Whitepapers
`PRESENTATION`	Präsentationen (PPT/Slides)
`VIDEO`	Video-Dateien
`AUDIO`	Audio-Dateien
`SPREADSHEET`	Tabellen (Excel/CSV)
`DATASHEET`	Datenblätter

API-Beispiele

Document hochladen (Single-File)

Schritt 1 — Document-Metadaten anlegen (JSON, KEIN File):

POST /api/elibrary/documents
Content-Type: application/json

{
  "title": "ITSM Whitepaper 2026",
  "type": "WHITEPAPER",
  "publisher": "Eviworx",
  "categoryId": "clx-cat-whitepapers",
  "collectionId": null,
  "tags": ["itsm", "whitepaper"]
}

Response (201 Created)

{
  "id": "clx-doc-id",
  "title": "ITSM Whitepaper 2026",
  "type": "WHITEPAPER",
  "publisher": "Eviworx",
  "category": { "id": "clx...", "name": "Whitepapers", "color": "#8b5cf6" },
  "collectionId": null,
  "tags": [
    { "id": "clx...", "name": "itsm" },
    { "id": "clx...", "name": "whitepaper" }
  ],
  "uploadedBy": { "id": "clx...", "name": "Legal Manager" },
  "createdAt": "2026-01-28T10:00:00Z",
  "isArchived": false
}

Schritt 2 — Datei zum erhaltenen documentId hochladen (zentrales Anhang-System, multipart):

POST /api/attachments/ELIBRARY_DOCUMENT/clx-doc-id
Content-Type: multipart/form-data   # field: file
# Download afterwards: GET /api/attachments/:attachmentId/download

Batch-Anlage mit Collection

Batch legt NUR Metadaten an (1–20 Dokumente, optional als Collection) und liefert die Document-IDs zurück. Die Dateien werden anschließend einzeln je documentId hochgeladen (siehe oben).

POST /api/elibrary/documents/batch
Content-Type: application/json

{
  "collectionName": "ISO 27001 Package 2026",
  "collectionDescription": "Audit documentation set",
  "categoryId": "clx-cat-compliance",
  "documents": [
    { "title": "ISMS Policy", "type": "PDF", "publisher": "Security", "tags": ["iso27001"] },
    { "title": "Risk Assessment", "type": "SPREADSHEET", "publisher": "Security", "tags": ["iso27001", "risk"] },
    { "title": "Audit Presentation", "type": "PRESENTATION", "publisher": "Security", "tags": ["iso27001"] }
  ]
}

Response (201 Created)

{
  "collection": {
    "id": "clx...",
    "name": "ISO 27001 Package 2026",
    "description": "Audit documentation set",
    "category": {
      "name": "Compliance",
      "color": "#8b5cf6"
    },
    "documentCount": 3,
    "createdBy": {
      "name": "Legal Manager"
    },
    "createdAt": "2026-01-28T10:00:00Z",
    "isArchived": false
  },
  "data": [
    { "id": "clx-1", "title": "ISMS Policy", "type": "PDF", "isArchived": false },
    { "id": "clx-2", "title": "Risk Assessment", "type": "SPREADSHEET", "isArchived": false },
    { "id": "clx-3", "title": "Audit Presentation", "type": "PRESENTATION", "isArchived": false }
  ]
}

File herunterladen

Der Download läuft über das zentrale Anhang-System. Die attachmentId kommt aus der Anhang-Liste des Dokuments:

# List the document's attachments → attachmentId
GET /api/attachments/ELIBRARY_DOCUMENT/:documentId
# Download the file
GET /api/attachments/:attachmentId/download

Document archivieren

PATCH /api/elibrary/documents/:id/archive

{
  "isArchived": true
}

Response

{
  "id": "clx...",
  "title": "GDPR Privacy Policy 2025",
  "isArchived": true,
  "archivedAt": "2026-01-28T10:30:00Z"
}

Collections

Collections gruppieren verwandte Documents (z.B. alle Dokumente zu einem Thema):

Collection erstellen

POST /api/elibrary/collections

{
  "name": "ISO 27001 Certification Documents",
  "description": "All documents required for ISO 27001 audit",
  "categoryId": "clx-cat-compliance"
}

Response

{
  "id": "clx...",
  "name": "ISO 27001 Certification Documents",
  "description": "All documents required for ISO 27001 audit",
  "category": {
    "id": "clx...",
    "name": "Policies & Compliance",
    "color": "#8b5cf6"
  },
  "documentCount": 0,
  "createdBy": {
    "name": "Compliance Manager"
  },
  "createdAt": "2026-01-28T11:00:00Z",
  "isArchived": false
}

Documents zu Collection hinzufügen

// On create (metadata):
POST /api/elibrary/documents
{ "title": "...", "type": "PDF", "publisher": "...", "categoryId": "...", "collectionId": "clx-collection-id" }

// Existing documents without a collection:
POST /api/elibrary/collections/clx-collection-id/documents
{
  "documentIds": ["clx-doc-1", "clx-doc-2"]
}

Filtering & Search

Filter-Parameter

Parameter	Beschreibung
`f.type`	PDF, EBOOK, WHITEPAPER, PRESENTATION, VIDEO, AUDIO, SPREADSHEET, DATASHEET
`f.categoryId`	Filter nach Category
`f.isArchived`	Filter nach Archivstatus (benötigt viewArchived, sonst 403)
`q`	Volltext (Titel / Publisher)
`standalone`	true = nur Dokumente ohne Collection (nur /documents)
`archived` / `includeArchived`	Flags: nur archivierte bzw. aktive + archivierte (benötigen viewArchived)
`page` / `per` / `sort`	Paginierung + Sortierung (per hat eine Obergrenze). Collection-Gruppierung via /documents/grouped.

Alle drei Listen (documents / collections / grouped) nutzen die Filter-Syntax oben. search, limit, sortBy, sortOrder, type und categoryId als einfache Parameter werden mit 400 LEGACY_QUERY_PARAM_REMOVED abgelehnt; ein unbekanntes f.<feld> ergibt 400 FILTER_FIELD_NOT_SUPPORTED. Die Batch-Anlage gelingt ganz oder gar nicht (201 { collection|null, data }).

Widersprüchliche Parameter werden abgelehnt: archived bzw. includeArchived zusammen mit f.isArchived sowie standalone zusammen mit f.collectionId ergeben 400 QUERY_SCOPE_CONFLICT. Die gruppierte Ansicht blättert höchstens bis zur Tiefe 2000 (page × per), darüber 400 MERGE_DEPTH_EXCEEDED, weil sie Collections und Einzeldokumente zusammenführt. /documents hat keine solche Grenze.

Beispiel-Queries

# All whitepapers
GET /api/elibrary/documents?f.type=WHITEPAPER

# By category
GET /api/elibrary/documents?f.categoryId=clx-cat-id

# Full-text search (title/publisher)
GET /api/elibrary/documents?q=itsm

# Standalone documents only (without a collection)
GET /api/elibrary/documents?standalone=true

# Grouped view (collections + standalone)
GET /api/elibrary/documents/grouped

# Archived documents (requires viewArchived)
GET /api/elibrary/documents?archived=true

Permissions

Permission	Beschreibung
`elibrary.view`	Documents & Collections anzeigen
`elibrary.viewArchived`	Archivierte Dokumente anzeigen — gilt auch für deren Dateien und für Änderungen an archivierten Einträgen
`elibrary.upload`	Documents hochladen
`elibrary.editOwn`	Eigene Documents bearbeiten (Uploader)
`elibrary.editAll`	Alle Documents bearbeiten
`elibrary.archive`	Documents archivieren/unarchivieren
`elibrary.delete`	Dokumente löschen (kritische Aktion, protokolliert)

viewArchived regelt jeden Zugriff auf archivierte Einträge: Wer eine archivierte Zeile nicht sehen darf, darf sie auch nicht ändern, entarchivieren oder löschen — Bearbeiten, Archiv-Umschalten und Löschen an einer BEREITS archivierten Zeile verlangen zusätzlich elibrary.viewArchived (Dokumente wie Collections). Das Archivieren einer sichtbaren Zeile ist ohne viewArchived erlaubt: es zählt immer nur der Ist-Zustand. Das gilt auch für die Dateien — Liste, Metadaten und Download der Anhänge archivierter Dokumente.

Sichtbarkeit entscheidet immer das Dokument: Eine Collection öffnet keine Dokumente — das Collection-Detail liefert nur Dokumente, die der Lesende ohnehin sehen darf. Dokumente in eine Collection aufzunehmen oder daraus zu entfernen verlangt daher das Bearbeitungsrecht am DOKUMENT (editAll bzw. editOwn als Uploader), nicht die Ownership an der Collection; eine unbekannte oder fremd zugeordnete Dokument-ID ist 404, ein Dokument aus einer anderen Collection wird nicht still umgehängt (400 DOCUMENT_ALREADY_IN_COLLECTION). Der Ersteller darf zusätzlich seine EIGENE, LEERE Collection löschen, auch ohne elibrary.delete — sonst bliebe nach einem fehlgeschlagenen Multi-Upload eine für ihn unlöschbare leere Collection zurück. Enthält sie Dokumente, ist elibrary.delete erforderlich.

Use-Cases

Use-Case 1: Policies & Compliance-Docs

// Create collection
POST /api/elibrary/collections
{
  "name": "Company Policies 2026",
  "categoryId": "clx-cat-policies"
}

// Batch CREATE documents (metadata, atomic) → { collection, data: [documents] }
POST /api/elibrary/documents/batch
{ "collectionName": "Company Policies 2026", "categoryId": "clx-cat-policies",
  "documents": [ { "title": "IT Security Policy", "type": "PDF", "publisher": "IT" } ] }
// Upload files afterwards per documentId: POST /api/attachments/ELIBRARY_DOCUMENT/:id

// Uses:
// - Onboarding: new employees get a link to the collection
// - Compliance audit: all policies in one place
// - Versioning: archive old version, upload new one

Use-Case 2: IT-Runbooks & Procedures

// Upload runbooks as PDF documents
{
  "title": "Incident Escalation Process",
  "type": "PDF",
  "publisher": "IT Operations",
  "categoryId": "clx-cat-procedures",
  "tags": ["incident", "escalation", "process"]
}

// Uses:
// - Agents have access via eLibrary
// - Alternative to Knowledge Base (KB = FAQ, eLibrary = formal docs)
// - Versioning via archive function

Use-Case 3: Forms & Templates

// Provide forms & templates
{
  "title": "Hardware-Request-Form.pdf",
  "type": "PDF",
  "publisher": "IT Department",
  "categoryId": "clx-cat-forms",
  "tags": ["hardware", "request", "form"]
}

{
  "title": "Monthly-Report-Template.xlsx",
  "type": "SPREADSHEET",
  "publisher": "Finance",
  "categoryId": "clx-cat-templates",
  "tags": ["report", "monthly", "template"]
}

// Uses:
// - Self-service for end users
// - Central template management
// - Downloads via the central attachment system

Best Practices

💡 Tipps

1. Organisation

• Nutze Collections für zusammengehörige Docs
• Categories nach Themen (Policies, Procedures, Forms)
• Tags für themenübergreifende Schlagworte (gdpr, iso27001, security)
• Publisher-Feld pflegen (für Verantwortlichkeiten)

2. Versionierung

• Alte Version archivieren (nicht löschen)
• Neue Version mit gleichem Titel hochladen
• Jahr im Titel für Versionierung (z. B. „Policy 2026")
• uploadedAt zeigt das Datum der Version

3. File-Management

• Max. Dateigröße / erlaubte Formate kommen aus den File-Settings für ELIBRARY_DOCUMENT (Admin-Center → System → Datei-Einstellungen, /admin/file-settings)
• Batch legt Metadaten an; Dateien danach je documentId hochladen
• Alle Uploads werden von ClamAV gescannt, bevor sie herunterladbar sind

4. Permissions

• Alle User: elibrary.view (können Docs sehen & downloaden)
• Power-User: upload, editOwn (können eigene Docs hochladen)
• Admins: editAll, archive, delete (volle Kontrolle)
• Archive-Permission für Compliance-Team

Error-Handling

Error Code	HTTP Status	Beschreibung
`ELIBRARY_DOCUMENT_NOT_FOUND`	404	Document-ID existiert nicht
`ELIBRARY_COLLECTION_NOT_FOUND`	404	Collection-ID existiert nicht
`ELIBRARY_CATEGORY_NOT_FOUND`	404	Category-ID existiert nicht
`NO_FILE`	400	Keine Datei im Upload-Request (Anhang-Upload)
`FILE_TOO_LARGE`	413	Datei über konfiguriertem Limit (File-Settings) — vom Attachment-Upload
`EXTENSION_NOT_ALLOWED` · `MIME_TYPE_NOT_ALLOWED`	415	Dateityp für ELIBRARY_DOCUMENT nicht erlaubt (Anhang-Upload)
`FORBIDDEN`	403	Fehlende Berechtigung (z. B. viewArchived, editAll). Fehlt schon das Grundrecht der Route, lautet error „Insufficient permissions", und das Feld required nennt das geforderte Recht (Aufbau siehe API-Übersicht)
`LEGACY_QUERY_PARAM_REMOVED`	400	Nicht unterstützter Query-Parameter (search/limit/sortBy/sortOrder/type/categoryId)
`FILTER_FIELD_NOT_SUPPORTED`	400	Unbekanntes f.<feld> in der Filter-Query
`QUERY_SCOPE_CONFLICT`	400	Widersprüchliche Parameter (archived/includeArchived + f.isArchived, standalone + f.collectionId)
`MERGE_DEPTH_EXCEEDED`	400	Blättertiefe der gruppierten Ansicht über 2000 (page × per)
`DOCUMENT_ALREADY_IN_COLLECTION`	400	Dokument gehört bereits zu einer Collection

Hinweis: Die eLibrary ist ideal für formale Dokumente (Policies, Procedures, Forms). Für FAQ-artige Inhalte nutze die Knowledge Base API.