Such-API

Volltextsuche

GET /api/search/

Durchsuche Titel und Inhalte von Knoten mit BM25-Ranking.

Parameter:

Parameter	Typ	Erforderlich	Standard	Beschreibung
q	string	ja	—	Suchanfrage
connection_id	UUID	nein	erste Verbindung des Nutzers	Bestimmte zu durchsuchende Verbindung
size	int	nein	50	Maximale Anzahl an Ergebnissen
highlight	bool	nein	true	Textauszüge mit Hervorhebungen einschließen
type	string	nein	all	Filter: page, database oder user

Beispiel:

curl -H "Authorization: Bearer <jwt_token>" \
  "https://ivgraph.com/api/search/?q=project+planning&size=10"

import requests

resp = requests.get(
    "https://ivgraph.com/api/search/",
    headers={"Authorization": "Bearer <jwt_token>"},
    params={"q": "project planning", "size": 10}
)
results = resp.json()["results"]

const resp = await fetch(
  "https://ivgraph.com/api/search/?q=project+planning&size=10",
  { headers: { Authorization: "Bearer <jwt_token>" } }
);
const { results } = await resp.json();

Antwort:

{
  "query": "project planning",
  "total": 8,
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "type": "page",
      "title": "Project Planning Guide",
      "score": 12.5,
      "highlight": "...comprehensive <em>project</em> <em>planning</em> methodology..."
    }
  ]
}

Autovervollständigung

GET /api/search/suggest/

Präfixbasierte Autovervollständigung für die Suche während der Eingabe.

Parameter:

Parameter	Typ	Erforderlich	Standard	Beschreibung
q	string	ja	—	Präfix (mindestens 2 Zeichen)
size	int	nein	10	Maximale Anzahl an Vorschlägen

Beispiel:

curl -H "Authorization: Bearer <jwt_token>" \
  "https://ivgraph.com/api/search/suggest/?q=pro"

Antwort:

{
  "prefix": "pro",
  "suggestions": [
    {"id": "uuid-1", "title": "Project Alpha", "type": "page"},
    {"id": "uuid-2", "title": "Product Roadmap", "type": "page"},
    {"id": "uuid-3", "title": "Projects Tracker", "type": "database"}
  ]
}

Semantische Suche

GET /api/search/semantic/

Vektorbasierte Ähnlichkeitssuche mit Embeddings. Findet Inhalte mit ähnlicher Bedeutung, nicht nur Übereinstimmungen bei Suchbegriffen.

Parameter:

Parameter	Typ	Erforderlich	Standard	Beschreibung
q	string	ja	—	Suchanfrage in natürlicher Sprache
connection_id	UUID	nein	erste Verbindung des Nutzers	Zu durchsuchende Verbindung
size	int	nein	10	Maximale Anzahl an Ergebnissen

Beispiel:

curl -H "Authorization: Bearer <jwt_token>" \
  "https://ivgraph.com/api/search/semantic/?q=how+do+we+handle+user+onboarding"

Antwort:

{
  "query": "how do we handle user onboarding",
  "total": 5,
  "search_type": "semantic",
  "results": [
    {"id": "uuid-1", "type": "page", "title": "New User Welcome Flow", "score": 0.89},
    {"id": "uuid-2", "type": "page", "title": "Onboarding Checklist", "score": 0.82}
  ]
}

Hybride Suche

GET /api/search/hybrid/

Kombiniert die BM25-Suche nach Suchbegriffen mit der semantischen Vektorsuche – für Ergebnisse, die das Beste aus beiden Ansätzen vereinen.

Parameter: Wie bei der semantischen Suche.

Beispiel:

curl -H "Authorization: Bearer <jwt_token>" \
  "https://ivgraph.com/api/search/hybrid/?q=authentication+flow"

Ähnliche Knoten

GET /api/search/similar/{node_id}/

Finde anhand von Vektor-Embeddings Knoten, die einem bestimmten Knoten ähneln.

Parameter:

Parameter	Typ	Erforderlich	Standard	Beschreibung
node_id	UUID	ja	—	ID des Ausgangsknotens (im URL-Pfad)
connection_id	UUID	nein	erste Verbindung des Nutzers	Zu durchsuchende Verbindung
size	int	nein	10	Maximale Anzahl an Ergebnissen

Beispiel:

curl -H "Authorization: Bearer <jwt_token>" \
  "https://ivgraph.com/api/search/similar/550e8400-e29b-41d4-a716-446655440001/"

Seiteninhalt

GET /api/search/content/{page_id}/

Rufe Seiteninhalte als Markdown und Klartext ab.

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
page_id	UUID	ja	Seiten-ID (im URL-Pfad)

Beispiel:

curl -H "Authorization: Bearer <jwt_token>" \
  "https://ivgraph.com/api/search/content/550e8400-e29b-41d4-a716-446655440001/"

Antwort:

{
  "page_id": "550e8400-e29b-41d4-a716-446655440001",
  "title": "Project Alpha",
  "markdown": "# Project Alpha\n\nMain project page...",
  "plain_text": "Project Alpha\nMain project page...",
  "has_content": true
}

Indexverwaltung

POST /api/search/index/

Stoße die Neuindexierung des Elasticsearch-Index für die Verbindung des Nutzers an.

curl -X POST -H "Authorization: Bearer <jwt_token>" \
  "https://ivgraph.com/api/search/index/"

Antwort:

{"message": "Indexing complete", "index_name": "ivg_conn-uuid", "indexed_count": 342}

DELETE /api/search/index/

Lösche den Suchindex für die Verbindung des Nutzers.

curl -X DELETE -H "Authorization: Bearer <jwt_token>" \
  "https://ivgraph.com/api/search/index/"

GET /api/search/connections/

Liste alle Suchindizes des Nutzers auf.

curl -H "Authorization: Bearer <jwt_token>" \
  "https://ivgraph.com/api/search/connections/"

Antwort:

{
  "user": "username",
  "connections": [
    {
      "connection_id": "conn-uuid",
      "schema_name": "airbyte_conn_uuid",
      "index_name": "ivg_conn-uuid",
      "document_count": 342,
      "last_sync": "2026-04-10T10:00:00Z"
    }
  ]
}

Fehler

Status	Bedeutung
400	Fehlende oder ungültige Abfrageparameter
401	Nicht authentifiziert
404	Verbindung oder Seite nicht gefunden
503	Elasticsearch nicht verfügbar