API-Referenz

API Referenz

Diese Seite dokumentiert die aktuell öffentlich verfügbaren REST-Endpunkte der Webanwendung. Der derzeitige öffentliche Umfang deckt vor allem Folgendes ab:

Ausführung funktionaler Agents
Administration von Memory-Typen
Administration von Memory-Objekten

Alle Endpunkte benötigen ein Bearer-Token.

Authentifizierung

Übergebe dein Server-Token im Authorization-Header:

curl https://your-instance.nara.de/api/endpoint \
  -H "Authorization: Bearer YOUR_SERVER_TOKEN" \
  -H "Content-Type: application/json"

Server-Tokens erzeugst du unter Settings > API & Security. Details dazu findest du unter Authentifizierung & Tokens.

Agent API

Die aktuelle öffentliche Agent API ist für funktionale Agents ausgelegt. Sie akzeptiert keine beliebigen Chat-Verläufe, sondern ruft einen benannten funktionalen Agent mit strukturierten Argumenten auf.

Ausführbare funktionale Agents auflisten

GET /api/agent/run

Gibt die funktionalen Agents deiner Organisation zurück, die über diese API ausführbar sind.

curl https://your-instance.nara.de/api/agent/run \
  -H "Authorization: Bearer YOUR_SERVER_TOKEN"

Beispielantwort:

{
  "agents": [{ "name": "classifyUnspsc" }, { "name": "summarizeTicket" }]
}

Funktionalen Agent ausführen

POST /api/agent/run

curl -X POST https://your-instance.nara.de/api/agent/run \
  -H "Authorization: Bearer YOUR_SERVER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentName": "classifyUnspsc",
    "args": {
      "title": "Drucker ist offline",
      "description": "Benutzer kann nicht über den Netzwerkdrucker drucken."
    }
  }'

Feld	Typ	Pflicht	Beschreibung
`agentName`	`string`	Ja	Name des auszuführenden funktionalen Agents
`args`	`unknown`	Ja	Strukturierte Nutzdaten, validiert gegen das konfigurierte Arguments-Schema des Agents

{
  "success": true,
  "sessionId": "api-7f6d9a32-f37a-4f69-b0bb-8bc6e4ea1f5c",
  "agentExecutionId": "cm123example",
  "agent": "classifyUnspsc",
  "output": {
    "unspsc": "43212105"
  },
  "messages": []
}

Wichtige Hinweise:

Der Agent muss unter diesem Namen in deiner Organisation existieren.
Der Agent muss vom Typ funktional sein.
Funktionale Agents, die auf interaktive Tools angewiesen sind, die nur in der App verfügbar sind, sind über diese API nicht ausführbar.
args muss zum konfigurierten Tool-Vertrag dieses funktionalen Agents passen.

Typische Fehlerfälle:

400 bei ungültigem Request-Body oder ungültigen Argumenten
404, wenn der Agentname nicht existiert
402, wenn nicht genug Credits für die Ausführung vorhanden sind

Memory API

Die öffentliche Memory REST API stellt aktuell Endpunkte für Typen und Objekte bereit.

Memory-Typen

Methode	Pfad	Beschreibung
`GET`	`/api/memory/types`	Memory-Typen auflisten
`POST`	`/api/memory/types`	Memory-Typ erstellen
`PUT`	`/api/memory/types/{id}`	Memory-Typ aktualisieren
`DELETE`	`/api/memory/types/{id}`	Memory-Typ löschen

Memory-Typen auflisten

curl https://your-instance.nara.de/api/memory/types \
  -H "Authorization: Bearer YOUR_SERVER_TOKEN"

Beispielantwort:

{
  "items": [
    {
      "id": "7d5d2f7f-7f4e-4609-9f2d-9e8ef5fd1111",
      "type": "TroubleshootingGuide",
      "displayName": "Troubleshooting Guide",
      "description": "Structured troubleshooting knowledge",
      "visibility": "PRIVATE",
      "version": 1,
      "jsonSchema": { "type": "object" },
      "idSchema": null,
      "groupNames": ["KNOWLEDGE"],
      "relations": []
    }
  ]
}

Memory-Typ erstellen

curl -X POST https://your-instance.nara.de/api/memory/types \
  -H "Authorization: Bearer YOUR_SERVER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "TroubleshootingGuide",
    "displayName": "Troubleshooting Guide",
    "description": "Structured troubleshooting knowledge",
    "jsonSchema": {
      "type": "object",
      "required": ["title"],
      "properties": {
        "title": { "type": "string" },
        "resolution": { "type": "string" }
      }
    },
    "groupNames": ["KNOWLEDGE"]
  }'

Unterstützte Felder im Create-Body:

type
displayName
description
visibility
jsonSchema
idSchema
embeddingSchema
groupNames
relations

Memory-Objekte

Methode	Pfad	Beschreibung
`GET`	`/api/memory/objects`	Memory-Objekte auflisten
`POST`	`/api/memory/objects`	Memory-Objekt erstellen
`PATCH`	`/api/memory/objects/{id}`	Memory-Objekt aktualisieren
`DELETE`	`/api/memory/objects/{id}`	Memory-Objekt löschen

Memory-Objekte auflisten

curl "https://your-instance.nara.de/api/memory/objects?type=TroubleshootingGuide&page=1&pageSize=20" \
  -H "Authorization: Bearer YOUR_SERVER_TOKEN"

Unterstützte Query-Parameter:

typeId
type
key
page
pageSize

Beispielantwort:

{
  "total": 1,
  "items": [
    {
      "id": "7ec6a9ba-32cf-4f51-b859-5e5c228f2222",
      "typeId": "7d5d2f7f-7f4e-4609-9f2d-9e8ef5fd1111",
      "key": "printer-offline-fix",
      "content": {
        "title": "Printer Offline Fix",
        "resolution": "Restart the spooler and verify connectivity."
      }
    }
  ]
}

Memory-Objekt erstellen

curl -X POST https://your-instance.nara.de/api/memory/objects \
  -H "Authorization: Bearer YOUR_SERVER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "typeId": "7d5d2f7f-7f4e-4609-9f2d-9e8ef5fd1111",
    "key": "printer-offline-fix",
    "content": {
      "title": "Printer Offline Fix",
      "resolution": "Restart the spooler and verify connectivity."
    }
  }'

Memory-Objekt aktualisieren

curl -X PATCH https://your-instance.nara.de/api/memory/objects/7ec6a9ba-32cf-4f51-b859-5e5c228f2222 \
  -H "Authorization: Bearer YOUR_SERVER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "title": "Printer Offline Fix",
      "resolution": "Restart the spooler service, then reconnect the printer."
    }
  }'

Fehlerbehandlung

Die Endpunkte geben JSON-Fehler mit einem error-Feld und bei Bedarf weiteren Details zurück.

Beispiel:

{
  "error": "Invalid request data"
}

Häufige Statuscodes:

Status	Bedeutung
`400`	Ungültiger Request-Body, Parameter oder Schema-Validierung
`401`	Fehlendes oder ungültiges Token
`403`	Admin-Zugriff erforderlich
`404`	Ressource nicht gefunden
`402`	Nicht genug Credits für Agent-Ausführung
`500`	Unerwarteter Serverfehler

Nächste Schritte

Authentifizierung & Tokens Server-Tokens für den API-Zugriff erzeugen und verwalten.

Agents verwalten Funktionale Agents konfigurieren, bevor du sie programmatisch aufrufst.

Memory & Wissen Schemas und Objekte verstehen, die von den Memory-Endpunkten verwendet werden.