API-Referenz

Alle Endpunkte werden relativ zur Basis-URL Ihrer Instanz aufgerufen — https://app.nara.de oder https://your-instance.nara.de. Authentifizieren Sie jede Anfrage wie unter API-Authentifizierung beschrieben; die folgenden Beispiele verwenden ein Server-Token. Schreibende Anfragen erfordern Content-Type: application/json.

Agent-Ausführung

Methode	Pfad	Beschreibung
GET	/api/agent/run	Ausführbare Workflow-Agents auflisten
POST	/api/agent/run	Einen Workflow-Agent per Name ausführen

Über die API lassen sich nur Workflow-Agents ausführen; Chat-Agents sind auf diesem Weg nicht ausführbar. Agents, deren Tools eine WEBAPP-Ausführung erfordern, können ebenfalls nicht über die API laufen.

Der Editor jedes Agents enthält außerdem den Dialog Call this agent via API, der den exakten Endpunkt, die Header und fertige Codebeispiele für diesen Agent anzeigt.

Ausführbare Agents auflisten

curl https://app.nara.de/api/agent/run \
  -H "Authorization: Bearer nara_sa_..."

Workflow-Agent ausführen

Body: agentName (der interne Name des Agents) und args (ein Objekt gemäß dem Eingabe-Datentyp des Agents).

curl -X POST https://app.nara.de/api/agent/run \
  -H "Authorization: Bearer nara_sa_..." \
  -H "Content-Type: application/json" \
  -d '{ "agentName": "invoice-classifier", "args": { "invoiceId": "INV-1042" } }'

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

curl https://app.nara.de/api/memory/types \
  -H "Authorization: Bearer nara_sa_..."

curl -X POST https://app.nara.de/api/memory/types \
  -H "Authorization: Bearer nara_sa_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customer",
    "displayName": "Customer",
    "schema": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "tier": { "type": "string" }
      }
    }
  }'

curl -X DELETE https://app.nara.de/api/memory/types/{id} \
  -H "Authorization: Bearer nara_sa_..."

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

Query-Parameter für die Auflistung

Parameter	Beschreibung
typeId	Nach Memory-Typ-ID filtern
type	Nach technischem Typnamen filtern
key	Nach Objektschlüssel filtern
page	Seitennummer
pageSize	Ergebnisse pro Seite

curl "https://app.nara.de/api/memory/objects?type=customer&page=1&pageSize=20" \
  -H "Authorization: Bearer nara_sa_..."

curl -X POST https://app.nara.de/api/memory/objects \
  -H "Authorization: Bearer nara_sa_..." \
  -H "Content-Type: application/json" \
  -d '{ "type": "customer", "contents": { "name": "Acme GmbH", "tier": "gold" } }'

curl -X PATCH https://app.nara.de/api/memory/objects/{id} \
  -H "Authorization: Bearer nara_sa_..." \
  -H "Content-Type: application/json" \
  -d '{ "contents": { "tier": "platinum" } }'

Rollen

Methode	Pfad	Beschreibung
GET	/api/roles	Rollen auflisten
POST	/api/roles	Benutzerdefinierte Rolle erstellen
GET	/api/roles/{id}	Rolle abrufen
PUT	/api/roles/{id}	Rolle aktualisieren
DELETE	/api/roles/{id}	Benutzerdefinierte Rolle löschen
POST	/api/roles/{id}/assign	Rolle einem Principal zuweisen
POST	/api/roles/{id}/unassign	Rolle einem Principal entziehen
GET	/api/roles/{id}/principals	Der Rolle zugewiesene Principals auflisten

Die integrierten Rollen Admin und Member können weder gelöscht noch umbenannt werden.

curl -X POST https://app.nara.de/api/roles \
  -H "Authorization: Bearer nara_sa_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Lead",
    "description": "Manages tickets and support access",
    "permissions": ["ticket.view", "ticket.update", "supportAccess.manage"]
  }'

curl -X POST https://app.nara.de/api/roles/{id}/assign \
  -H "Authorization: Bearer nara_sa_..." \
  -H "Content-Type: application/json" \
  -d '{ "principalType": "USER", "principalId": "<user-id>" }'

curl https://app.nara.de/api/roles/{id}/principals \
  -H "Authorization: Bearer nara_sa_..."

Fehler

Alle Endpunkte verwenden die gemeinsamen Statuscodes aus der API-Authentifizierung: 400 ungültiger Body, 401 Authentifizierungsfehler, 402 unzureichende Credits, 403 Berechtigung verweigert, 404 nicht gefunden, 500 Serverfehler.