Zum Inhalt

API-Beispiele

Die Beispiele rufen https://app.nuvoca.ai/api/external/v1 mit einem API-Schlüssel oder REST-OAuth-Access-Token und den jeweils genannten Scopes auf.

Lade NUVOCA_ACCESS_TOKEN aus einem geschützten Zugangsdaten-Speicher. Halte den Wert aus Skripten, Shell-Historie und HTTP-Logs heraus.

Verbindung und Auswahl prüfen

Scopes: connection:verify, agents:read, agents:configuration:read.

curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer ${NUVOCA_ACCESS_TOKEN}" \
  "https://app.nuvoca.ai/api/external/v1/connection"

curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer ${NUVOCA_ACCESS_TOKEN}" \
  "https://app.nuvoca.ai/api/external/v1/agent-catalog"

curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer ${NUVOCA_ACCESS_TOKEN}" \
  "https://app.nuvoca.ai/api/external/v1/agent-catalog/voices?language=de&page=0&size=25"

Prüfe Workspace-Name und freigegebene Scopes. Übernimm ein erlaubtes Modell und eine passende voiceId aus den Katalogen. Ein Zugang ohne connection:verify kann andere freigegebene Operationen trotzdem nutzen.

Einen deaktivierten Voice Agent erstellen

Zusätzlicher Scope: agents:write. Speichere das folgende Beispiel als agent.json. GPT_4_1_MINI und azure:FLORIAN_HD sind Beispielwerte; ersetze sie, falls sie in deinem Katalog nicht auswählbar sind. Verwende synthetische Testdaten.

{
  "agent": {
    "enabled": false,
    "agentType": "VOICE",
    "title": "NuvoCar Empfang – Entwurf",
    "agentName": "NuvoCar Assistent",
    "sttProvider": "AZURE",
    "sttLanguages": ["de-DE"],
    "voiceId": "azure:FLORIAN_HD",
    "timezone": "Europe/Berlin",
    "greetingMorningText": "Guten Morgen, hier ist der digitale Assistent von NuvoCar. Wie kann ich helfen?",
    "greetingAfternoonText": "Guten Tag, hier ist der digitale Assistent von NuvoCar. Wie kann ich helfen?",
    "greetingEveningText": "Guten Abend, hier ist der digitale Assistent von NuvoCar. Wie kann ich helfen?",
    "initialSilenceTimeoutMs": 1500,
    "segmentationSilenceTimeoutMs": 500,
    "phraseList": ["NuvoCar"]
  },
  "options": {
    "model": "GPT_4_1_MINI",
    "systemPrompt": "Du bist der digitale Empfang von NuvoCar. Frage nach dem Anliegen. Erfinde keine Preise oder Termine. Erkläre offen, wenn eine Auskunft fehlt. Behaupte keine Speicherung oder Weiterleitung ohne erfolgreiche konfigurierte Aktion.",
    "conversationHistoryLimit": 20,
    "knowledgeBaseId": null,
    "ragTopK": 5,
    "ragSimilarityThreshold": 0.5,
    "temperature": 0.3,
    "maxTokens": 1000,
    "ttsStreamingMode": "QUALITY_SSML",
    "queryTransformEnabled": false,
    "queryTransformHistoryLimit": 5,
    "queryTransformConfidenceThreshold": 0.8,
    "queryTransformMode": "LLM"
  }
}

curl --fail-with-body --silent --show-error \
  --request POST \
  --header "Authorization: Bearer ${NUVOCA_ACCESS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data-binary @agent.json \
  "https://app.nuvoca.ai/api/external/v1/agents"

Die Antwort liefert die Agent-ID und Revision. Der Entwurf hat weder Rufnummer noch zugewiesene Tools. Er startet keinen Anruf. Zum produktiven Einsatz ergänze und teste die Agent-Konfiguration.

Einen Prompt ohne Überschreiben fremder Änderungen aktualisieren

  1. Rufe GET /agents/{id} ab. Lies den Response-Header ETag und die vollständigen Objekte agent und options.
  2. Ändere nur options.systemPrompt in der gelesenen Konfiguration. Der PUT-Body enthält agent und options, nicht die äußeren Antwortfelder id oder revision.
  3. Sende PUT auf denselben Pfad mit Content-Type: application/json und If-Match mit dem vollständigen ETag aus Schritt 1.
  4. Bei 409 erneut lesen und deinen Vorschlag abgleichen. Übernimm den neuen ETag nicht ungeprüft für den alten Body.
PUT /api/external/v1/agents/AGENT_ID
Authorization: Bearer REST_ACCESS_TOKEN
Content-Type: application/json
If-Match: "REVISION_AUS_GET"

Die Platzhalter im Header-Beispiel sind zu ersetzen. Eine Agent-Revision ist ein zusammengesetzter Wert; behandle sie als undurchsichtigen String und berechne sie nicht selbst.

Eine Wissensdatei hochladen

Scopes: knowledge-bases:read, knowledge-bases:write, documents:read, documents:write. Erstelle zunächst eine Knowledge Base per POST auf /knowledge-bases mit diesem Body:

{"title": "NuvoCar Servicewissen"}

Übernimm ihre ID als NUVOCA_KB_ID. Lade danach die geprüfte lokale Datei hoch:

curl --fail-with-body --silent --show-error \
  --request POST \
  --header "Authorization: Bearer ${NUVOCA_ACCESS_TOKEN}" \
  --form-string "title=Servicewissen" \
  --form "file=@servicewissen.md;type=text/markdown" \
  "https://app.nuvoca.ai/api/external/v1/knowledge-bases/${NUVOCA_KB_ID}/documents"

Setze den Multipart-Content-Type nicht von Hand; der Client ergänzt die Boundary. Weise die Knowledge Base anschließend mit options.knowledgeBaseId einem Agenten zu; dafür benötigst du zusätzlich Agent-Konfigurationslese- und Schreibrechte. Teste echte Wissensfragen, bevor du die Sammlung produktiv nutzt.

Einen lokalen Tag an Zusammenfassungen lesen

Scope: call-summaries:read. Dieses feste Beispiel wählt den 2. November 2026 in Europe/Berlin, von 00:00 Uhr einschließlich bis 00:00 Uhr des Folgetags ausschließlich. Beide Grenzen liegen an diesem Datum bei UTC+1.

curl --fail-with-body --silent --show-error --get \
  --header "Authorization: Bearer ${NUVOCA_ACCESS_TOKEN}" \
  --data-urlencode "from=2026-11-02T00:00:00+01:00" \
  --data-urlencode "to=2026-11-03T00:00:00+01:00" \
  --data-urlencode "page=0" \
  --data-urlencode "size=100" \
  "https://app.nuvoca.ai/api/external/v1/call-summaries"

Für „heute“ berechnest du beide lokalen Mitternachtsgrenzen mit der IANA-Zeitzone und wandelst sie anschließend in ISO-Zeitstempel um. Verwende keine fest verdrahtete Tageslänge oder einen ganzjährigen Offset. URL-Encoding erhält insbesondere das Pluszeichen im Offset korrekt.

Erhöhe page, bis alle totalPages abgerufen sind. Respektiere bei 429 den Retry-After-Header. Die Ergebnisse enthalten auch Rufnummern und möglicherweise personenbezogene Inhalte; speichere oder protokolliere sie nur für den vorgesehenen Zweck. Prüfe die Auswahl- und Schwärzungsregeln, bevor du aus fehlenden Ergebnissen Schlüsse ziehst. Einen passenden Analyseauftrag findest du unter Rückrufbedarf prüfen.