Skip to content

API.md

Latest commit

 

History

History
286 lines (191 loc) · 4.1 KB

API.md

File metadata and controls

286 lines (191 loc) · 4.1 KB
Raw

API Dokumentation

Basis-URL lokal:

http://localhost:3001

Alle API-Routen liegen unter:

/api

Authentifizierung

Aktuell ist keine API-Authentifizierung implementiert. Für produktive Nutzung sollte ein Auth-Layer vorgeschaltet werden.

Health

GET /health

Prüft API-Liveness und MongoDB-Erreichbarkeit.

Antwort:

{"ok": true}

Providers

GET /api/providers

Listet alle Provider-Dokumente.

POST /api/providers

Erzeugt neuen Provider.

Beispiel:

{
  "name": "OpenAI",
  "slug": "openai",
  "base_url": "https://api.openai.com/v1",
  "api_key_plain": "sk-...",
  "is_active": true,
  "capabilities": {
    "chat": true,
    "embeddings": true,
    "vision": true,
    "function_calling": true,
    "json_mode": true
  }
}

Hinweise:

  • api_key_plain wird serverseitig verschlüsselt und als api_key_encrypted gespeichert.
  • Antwort maskiert das Feld als ***.

PUT /api/providers/:id

Aktualisiert Provider-Teilfelder.

Spezialfall:

  • Bei api_key_plain wird neu verschlüsselt gespeichert.

DELETE /api/providers/:id

Löscht Provider.

Antwort: 204 No Content

POST /api/providers/:id/sync-models

Synchronisiert verfügbare Modelle vom Provider-Endpunkt (client.models.list()).

Antwort:

{"ok": true}

Entity Types

GET /api/entity-types

Liest alle Entitätstypen.

Entities

GET /api/entities

Query-Parameter:

  • page (default 1)
  • limit (default 20)
  • type (filtert entity_type_slug)
  • search (Mongo Textsuche auf Name/Keywords/Digest)

Antwort:

{
  "items": [],
  "total": 0,
  "page": 1,
  "limit": 20
}

POST /api/entities

Erzeugt Entität.

Minimalbeispiel:

{
  "name": "ACME GmbH",
  "entity_type_slug": "company"
}

GET /api/entities/:id

Liest einzelne Entität.

PUT /api/entities/:id

Patch-Update; Felder aus Request werden direkt gesetzt.

DELETE /api/entities/:id

Löscht Entität.

Antwort: 204 No Content

POST /api/entities/:id/crawl-now

Queue't manuellen Skill-Run.

Body:

{
  "skill_slug": "rss",
  "config": {
    "feed_urls": ["https://example.com/feed.xml"],
    "max_items_per_fetch": 20
  }
}

Antwort:

{"queued": true}

POST /api/entities/:id/compress

Queue't Komprimierung für die Entität.

Antwort:

{"queued": true}

GET /api/entities/:id/chunks

Paginiert Chunks zur Entität.

Query-Parameter:

  • page (default 1)
  • limit (default 20)

Antwort:

{
  "items": [],
  "total": 0,
  "page": 1,
  "limit": 20
}

Routing

GET /api/routing

Liest alle Model-Routing-Regeln.

PUT /api/routing/:taskType

Aktualisiert Routing-Regel für einen Task-Type, z. B.:

  • extraction
  • compression
  • schema_discovery
  • embedding
  • summarization
  • prompt_optimization
  • relationship_detection
  • entity_classification

Skills

GET /api/skills

Liest Skill-Definitionen aus Datenbank.

GET /api/skills/:slug

Liest ein Skill-Dokument.

404, falls nicht vorhanden.

Monitoring

GET /api/monitor/stream

SSE-Endpunkt (text/event-stream).

Events:

  • init
  • audit (Array neuer Audit-Einträge)

GET /api/monitor/stats

Antwort:

{"total": 1234}

GET /api/monitor/costs?period=today|week

Antwort:

{
  "period": "today",
  "total_cost": 0,
  "tokens": 0
}

Ingest

POST /api/ingest/file

Multipart-Upload.

Form-Fields:

  • file (pflicht)
  • entity_id (optional)
  • processing_mode (optional, default auto)

Verhalten:

  • Mit entity_id: Datei wird bestehender Entität zugeordnet.
  • Ohne entity_id: neue document-Entität wird erzeugt.
  • Danach wird file-Skill-Job enqueued.

Antwort:

{
  "ok": true,
  "entity_id": "65f...",
  "file": "1700000000000-my-file.txt"
}

Fehlerverhalten

Typische Fehlercodes:

  • 400 bei fehlender Datei im Ingest
  • 404 bei unbekannter Ressource
  • 500 bei Infrastruktur- oder Laufzeitfehlern

Aktuell existiert kein zentrales Error-Envelope-Schema. Für produktive Integrationen wird ein einheitliches Fehlerformat empfohlen.