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 API-Principal-Token. Schreibende Anfragen erfordern Content-Type: application/json.

Runs

Methode	Pfad	Beschreibung
POST	/api/v1/runs	Run starten
GET	/api/v1/runs/{runId}	Run-Quittung lesen
GET	/api/v1/runs/{runId}/events	Run-Events streamen (SSE)
POST	/api/v1/runs/{runId}/approve	Ausstehende Freigabe entscheiden
POST	/api/v1/runs/{runId}/cancel	Kooperativen Abbruch anfordern

Runs authentifizieren sich mit einem API-Principal-Token, das Ihr nara-Betreiber ausstellt. Jeder Principal ist an einen Assistenten gebunden; der Run läuft mit den Fähigkeiten dieses Assistenten. Der Header Idempotency-Key ist Pflicht — derselbe Key liefert denselben Run, ein anderer Body unter demselben Key liefert 409.

Run starten

Body: input, ein Array typisierter Inhaltsblöcke — { "type": "text", "text": … }, { "type": "json", "value": … }, { "type": "file", "fileId": … } oder { "type": "reference", "source": …, "targetId": … } — plus optional skillId für einen delegierbaren Skill des gebundenen Assistenten. Datei- und Referenz-Handles müssen zu Ihrer Organisation gehören. Es gibt keine Modell-, Prompt-, Tool- oder Richtlinien-Overrides.

curl -X POST https://app.nara.de/api/v1/runs \
  -H "Authorization: Bearer nara_sa_..." \
  -H "Idempotency-Key: 6f4f2c1e-4b7a-4a4e-9c1d-2f8e5a1b0c3d" \
  -H "Content-Type: application/json" \
  -d '{ "input": [{ "type": "text", "text": "Rechnung INV-1042 klassifizieren" }] }'

Die Antwort ist 202 mit { "runId": …, "status": "running" }. Mit Prefer: wait=30 erhalten Sie direkt die fertige Quittung, wenn der Run innerhalb des Wartefensters abschließt.

Die Run-Quittung

GET /api/v1/runs/{runId} liefert die feste Quittungsstruktur: status, message, structuredResult, artifacts, citations, sideEffectReceipts, unresolved (ausstehende Freigaben) und usage. Ein Run ohne ausreichende Credits endet mit dem Status failed und dem Grund in error; die Anfrage selbst liefert kein 402.

Events

GET /api/v1/runs/{runId}/events streamt das redigierte Event-Protokoll des Runs als SSE. Jeder Frame trägt eine id; mit dem Standard-Header Last-Event-ID setzen Sie den Cursor beim Reconnect fort.

Freigaben

Freigabepflichtige Aktionen laufen nie im Run selbst. Sie erscheinen unter unresolved in der Quittung und warten auf den gebundenen Genehmiger des Principals: einen benannten Benutzer, jeden Organisations-Admin (live geprüft) oder einen separaten Genehmiger-Principal. Das eigene Token des Runs kann nie freigeben.

curl -X POST https://app.nara.de/api/v1/runs/{runId}/approve \
  -H "Authorization: Bearer <Genehmiger-Credential>" \
  -H "Content-Type: application/json" \
  -d '{ "operationId": "…", "approved": true }'

Abbrechen

POST /api/v1/runs/{runId}/cancel setzt den Run auf cancelling; er stoppt an der nächsten sicheren Grenze, begonnene Aktionen schließen mit Quittungen ab.

Datentypen

Methode	Pfad	Beschreibung
GET	/api/knowledge/types	Datentypen auflisten
POST	/api/knowledge/types	Datentyp erstellen
PUT	/api/knowledge/types/{id}	Datentyp aktualisieren
DELETE	/api/knowledge/types/{id}	Datentyp löschen

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

curl -X POST https://app.nara.de/api/knowledge/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/knowledge/types/{id} \
  -H "Authorization: Bearer nara_sa_..."

Wissenseinträge

Methode	Pfad	Beschreibung
GET	/api/knowledge/objects	Wissenseinträge auflisten
POST	/api/knowledge/objects	Wissenseintrag erstellen
PATCH	/api/knowledge/objects/{id}	Wissenseintrag aktualisieren
DELETE	/api/knowledge/objects/{id}	Wissenseintrag löschen

Query-Parameter für die Auflistung

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

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

curl -X POST https://app.nara.de/api/knowledge/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/knowledge/objects/{id} \
  -H "Authorization: Bearer nara_sa_..." \
  -H "Content-Type: application/json" \
  -d '{ "contents": { "tier": "platinum" } }'

Rollen und Gruppen

Rollen, Gruppen, Mitgliedschaften und Ressourcenfreigaben sind nicht über die öffentliche REST-API verfügbar. Verwalten Sie sie unter Organization (/admin/organization) und Access Control (/admin/rbac).

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.