Kalima REST API v1

Mit der Kalima REST API kann Ihre eigene Integration die Aufnahmen lesen, die Ihnen gehören, samt Transkript, KI-Zusammenfassung, Aufgaben und Momenten. Sie kann Audiodateien zur Transkription hochladen und Aufnahmen ordnen: Projekte, Namen, Sprecher, Freigabelinks und Zusammenfassungen.

Anmeldung

Es gibt zwei Wege:

• API-Schlüssel (Pro, Team und Enterprise) für eigene Skripte und Integrationen. Senden Sie den Schlüssel bei jeder Anfrage als Bearer-Token.
• OAuth (ab Plus) für die Automatisierungsplattformen, die Kalima registriert hat. Diese bitten Sie in einem Kalima-Fenster, die Verbindung zu bestätigen. Unter Einstellungen, Integrationen, Verbundene Apps können Sie eine solche Verbindung jederzeit entfernen.

Authorization: Bearer kal_xxxxxxxxxxxxxxxxxxxx

Ein API-Schlüssel hat die Berechtigung read, write oder beide. read deckt alle Listen, Suchen, Feeds und Exporte ab. write brauchen Sie nur, wenn die Integration Audio hochlädt oder Aufnahmen und Projekte ändert. Jede Anfrage gilt für das Konto, dem der Schlüssel gehört, und sieht nur dessen eigene Aufnahmen.

Endpunkte

Basis-URL: https://meetkalima.com/api/v1

Jede Aufnahme trägt url, den Link, der sie in Kalima öffnet, und dazu Projekt und Arbeitsbereich, in denen sie liegt.

Aufnahmen auflisten

GET /recordings liefert standardmäßig den Feed fertiger Aufnahmen. Eine Aufnahme kommt genau einmal hinein, sobald nichts mehr in sie aufgenommen wird und sich ihr Transkript seit zwei Minuten nicht geändert hat. Ihren Platz behält sie danach, auch wenn Sie das Transkript später korrigieren. Wird später weiter in sie aufgenommen, kommt sie nicht ein zweites Mal hinein. Die neuesten Einträge stehen oben, und jeder trägt finishedAt, den Zeitpunkt, zu dem er in den Feed kam. Deshalb können Sie den Feed regelmäßig abfragen und jede id genau einmal verarbeiten, ohne ein Transkript zu erwischen, das noch wächst. Auch eine hochgeladene Datei ohne Sprache kommt hinein, mit segmentCount 0. So erfährt die Integration, die sie hochgeladen hat, dass sie fertig ist. Beim ersten Abruf reicht der Feed sieben Tage zurück.

Mit status=all erhalten Sie alle Aufnahmen in jedem Zustand, die neuesten zuerst, mit status=failed nur die Uploads, deren Transkription fehlgeschlagen ist. Jede Aufnahme hat einen status (recording, processing, failed oder ready), und updatedAt gibt an, wann sich Transkript oder Sprecher zuletzt geändert haben. Mit projectId oder workspaceId grenzen Sie jede dieser Listen ein.

Listen kommen seitenweise. Geben Sie den nextCursor einer Antwort als cursor zurück, bis er null ist. limit legt die Seitengröße fest (1 bis 100, Standard 25).

Wenn Sie nur Neues abrufen möchten, übergeben Sie die höchste sequence, die Sie kennen, als afterSequence. Jeder Eintrag im Feed trägt eine. Anders als finishedAt (das finishedAfter nimmt) bleibt sie genau, auch wenn viele Aufnahmen in derselben Millisekunde in den Feed kommen. Mit include=summary oder include=transcript,summary erhalten Sie den Inhalt direkt mit jedem Eintrag. Mit Transkript enthält eine Seite höchstens 10 Aufnahmen.

GET /recordings/search?q=budget findet Aufnahmen, in deren Name oder Transkript die Wörter vorkommen. Die beste Übereinstimmung steht oben, und jede bringt mit snippet die Stelle mit, an der die Wörter stehen. limit geht bis 25 (Standard 10), projectId oder workspaceId grenzen die Suche ein.

Eine Aufnahme lesen

GET /recordings/{id} liefert die Aufnahme mit transcriptText (Zeilen der Form Sprecher: Text) und summary. Die Zusammenfassung enthält einen Überblick, die wichtigsten Punkte, Aufgaben mit verantwortlicher Person und Termin, Entscheidungen, offene Fragen und die vollständige Zusammenfassung als Markdown. Solange für die Aufnahme keine Zusammenfassung erstellt wurde, ist summary gleich null.

Mit include=transcript, include=summary oder einem leeren include= laden Sie weniger. Ein Transkript mit mehr als 500.000 Zeichen wird an dieser Stelle abgeschnitten, transcriptTruncated ist dann true. Das vollständige Transkript in Abschnitten liefert GET /recordings/{id}/transcript.

GET /recordings/{id}/export?format=srt liefert die Aufnahme als Datei. Es ist dieselbe Datei, die der Export-Dialog in Kalima herunterlädt, und ihr Name steht im Header Content-Disposition. Als format gibt es txt, md, srt, vtt, json und summary-md. Hat die Aufnahme eine Übersetzung, exportiert track=translation bei md, srt und vtt die Übersetzung.

Feeds

Drei weitere Feeds funktionieren wie der Feed fertiger Aufnahmen. Die neuesten Einträge stehen oben und jeder kommt nur einmal. Mit cursor blättern Sie zurück, mit createdAfter holen Sie nur, was nach einem bestimmten Zeitpunkt hinzukam. Bei Zusammenfassungen und Aufgaben geht das mit afterSequence auch exakt. limit geht bis 50 (Standard 25), und projectId oder workspaceId grenzen jeden Feed ein.

• GET /summaries enthält einen Eintrag, sobald eine Aufnahme ihre KI-Zusammenfassung bekommt, und einen weiteren, wenn die Zusammenfassung neu erstellt oder bearbeitet wird. Jeder Eintrag enthält die vollständige Zusammenfassung und eine version: 1 für die erste Zusammenfassung einer Aufnahme, danach 2, 3 und so weiter. Umbenennen oder Verschieben bringt eine Zusammenfassung nicht erneut in den Feed. Er enthält die Zusammenfassungen der letzten sieben Tage.
• GET /action-items enthält jede Aufgabe aus diesen Zusammenfassungen einzeln, mit owner und due, wenn die Zusammenfassung sie nennt. Wird eine Zusammenfassung neu erstellt und die Aufgabe bleibt, behält sie ihre id. So kommt sie nicht doppelt an. Hier zählt limit die Zusammenfassungen, nicht die Aufgaben.
• GET /moments enthält die Momente, die beim Aufnehmen markiert wurden, mit KI-Titel und Position in der Aufnahme. Ein Moment wartet bis zu fünf Minuten auf seinen Titel, bevor er erscheint. Wann das war, steht in listedAt, und createdAfter vergleicht mit diesem Wert.

Aufnahmen ordnen

Dafür ist die Berechtigung write nötig.

• Umbenennen oder verschieben: PATCH /recordings/{id} mit name und wahlweise projectId oder workspaceId, nicht mit beiden. Beim Verschieben in ein Projekt kommt die Aufnahme wie in der App auch in den Arbeitsbereich des Projekts. Dafür brauchen Sie dort Bearbeitungsrechte, sonst lautet die Antwort PROJECT_ROLE_REQUIRED. Mit projectId: null nehmen Sie sie aus ihrem Projekt heraus. Wird das Verschieben abgelehnt, ändert sich nichts, auch nicht der Name.
• Sprecher benennen: PUT /recordings/{id}/speakers mit { "names": { "Speaker 1": "Anna Weber" } }. Jeder Schlüssel ist ein Sprecher, so wie das Transkript ihn zeigt, ein bereits vergebener Name oder ein Schlüssel aus GET /recordings/{id}/speakers. Ein leerer Name entfernt den Namen. Passt ein Schlüssel zu keinem Sprecher, wird die Anfrage mit SPEAKER_NOT_FOUND abgelehnt.
• Zusammenfassung erstellen: POST /recordings/{id}/summary antwortet mit der Zusammenfassung, wenn es eine gibt. Andernfalls kommt 202 mit status: "queued" zurück, und die Zusammenfassung erscheint nach ein bis zwei Minuten in GET /summaries und an der Aufnahme. Das verbraucht wie der Button „Zusammenfassung erstellen“ eine KI-Zusammenfassung aus Ihrem Tarif. Sind die Zusammenfassungen Ihres Tarifs aufgebraucht, kommt QUOTA_EXCEEDED zurück und nichts wird eingereiht. Wird gerade noch eine Datei in die Aufnahme transkribiert, kommt RECORDING_NOT_READY.
• Freigeben: POST /recordings/{id}/share-link schaltet den Freigabelink der Aufnahme ein und gibt ihn zurück. Jede Aufnahme hat einen Link, ein erneuter Aufruf liefert also denselben. Ein neuer Link öffnet sich für alle, die bei Kalima angemeldet sind und den Link haben. Die Freigaberegeln Ihrer Organisation gelten, und weiter oder enger stellen Sie den Zugriff in der App ein.
• Projekte: GET /projects listet die Projekte, die Ihnen gehören oder mit Ihnen geteilt sind, die neuesten zuerst. Mit name finden Sie Namen, die den Text enthalten, ohne Rücksicht auf Groß- und Kleinschreibung oder Akzente, mit zusätzlich exact=true nur genau diesen Namen. editable=true zeigt nur Projekte, in die Sie Aufnahmen ablegen dürfen. Jedes Projekt trägt dazu canEdit. POST /projects legt ein Projekt mit name an, optional mit description, workspaceId und parentProjectId (eine Ebene tief). Die Projektgrenze Ihres Tarifs gilt (PLAN_LIMIT_REACHED). GET /workspaces listet Ihre Arbeitsbereiche.

Audio hochladen

Senden Sie multipart/form-data mit einem Feld file. Diese Felder können Sie zusätzlich mitsenden:

curl -X POST "https://meetkalima.com/api/v1/recordings" \
  -H "Authorization: Bearer kal_xxx" \
  -F "file=@meeting.mp3" \
  -F "name=Weekly sync" \
  -F "languages=de,en"

Die Antwort (202) enthält die id der neuen Aufnahme mit dem Status processing. Fragen Sie GET /recordings/{id}?include= ab, bis der Status ready oder failed ist. Die transkribierte Dauer wird vom Transkriptionsguthaben des Kontos abgezogen.

Firma verwalten (Admin-API)

Für Firmen, die kein SCIM nutzen: Ein API-Schlüssel der Firma mit Verwaltungsrechten verwaltet Mitglieder, Teams und Richtlinien Ihrer Firma. Ein Inhaber oder Administrator erstellt ihn in der Kalima Console unter Integrationen & API, Schlüssel erstellen, im Abschnitt Verwaltung der Firma. Dort bekommt jeder Bereich keinen Zugriff, Lesen oder Lesen und ändern. Siehe Integrationen und Webhooks.

Der Schlüssel handelt als die Person, die ihn erstellt hat, mit ihrer Rolle. Sobald sie nicht mehr aktiver Inhaber oder Administrator ist, lehnen diese Pfade ihn ab (ADMIN_ROLE_REQUIRED). Es gelten dieselben Regeln wie in der Console: die Zahl der Plätze, einen Inhaber ändert nur ein Inhaber, mindestens ein aktiver Inhaber bleibt, und solange Ihr Identitätsanbieter Personen und Teams über SCIM verwaltet, sperrt er diese Personen und schaltet sie wieder frei und bestimmt, wer in diesen Teams ist und wie sie heißen (SCIM_MANAGED). Rollen und Teamleitung bleiben bei Kalima. Eine Ablehnung nennt den Grund aus der Console als code, zum Beispiel SEAT_CAP_REACHED, OWNER_PROTECTED oder LAST_OWNER. Jede Änderung steht im Audit-Log Ihrer Firma unter „API-Schlüssel“ und dem Namen des Schlüssels. Aufnahmen, Transkripte sowie Aktivität oder Nutzung einzelner Personen geben diese Pfade nie heraus. OAuth-Tokens (API_KEY_REQUIRED) und Schlüssel privater Konten (COMPANY_KEY_REQUIRED) werden abgelehnt.

• Mitglieder: GET /admin/members listet aktive und gesperrte Mitglieder auf, Inhaber zuerst. status und email grenzen die Liste ein, geblättert wird wie bei den anderen Listen mit cursor (limit 1 bis 500, Standard 100). PATCH /admin/members/{userId} ändert pro Anfrage eine Sache: { "role": "member" } (admin, member oder viewer) oder { "status": "suspended" } (oder active). Die Inhaberschaft wechselt nur durch eine Übergabe, die die neue Person annimmt, begonnen in den Einstellungen der Console oder in der App. Wer gesperrt wird, behält jede Aufnahme dort, wo sie ist.
• Einladen: POST /admin/invitations mit email, role und optional teamId. Die Person bekommt die übliche Einladungsmail. Darin steht als einladende Person, wer den Schlüssel erstellt hat.
• Teams: POST /admin/teams mit name und optional description, PATCH /admin/teams/{teamId} benennt es um. POST /admin/teams/{teamId}/members mit { "userId": "...", "role": "lead" } nimmt ein aktives Mitglied auf, PATCH /admin/teams/{teamId}/members/{userId} mit { "role": "member" } ändert die Teamleitung, und DELETE nimmt die Person aus dem Team. Ein Team löschen Sie weiterhin in der Console.
• Richtlinien: GET /admin/policies liefert die Abschnitte der Seite Richtlinien in der Console (data, ai, sharing, members, recording, projectSharing). PATCH nimmt dieselben Abschnitte und legt jeden über den gespeicherten Stand. Eine Einstellung, die Sie weglassen, bleibt also unverändert. Die Löschregeln ändern Sie nur in der Console, denn dort ist dafür ein zweiter Faktor nötig: Das automatische Löschen von Aufnahmen und Audio gehört nicht zum Body, und ein PATCH, der Zero Data Retention ein- oder ausschalten würde, wird mit CONSOLE_ONLY abgelehnt.

Das Anfragekontingent ist dasselbe wie für alle anderen Aufrufe. Lässt Ihre Firma Kalima nur aus bestimmten Netzwerken zu, ob nur für die Console oder für alles, antworten diese Pfade von überall sonst mit NETWORK_NOT_ALLOWED. Siehe Erlaubte Netzwerke.

Bei einem Firmenkonto gelten die Regeln der Firma auch für gewöhnliche API-Schlüssel: Ist Zapier und die öffentliche API oder API-Schlüssel unter Richtlinien in der Console ausgeschaltet, werden Anfragen mit Schlüsseln von Konten dieser Firma mit 403 und ORG_POLICY_BLOCKED abgewiesen. Siehe Richtlinien.

Fehler und Grenzen

Jeder Fehler hat dieselbe Form:

{ "error": { "code": "RECORDING_NOT_FOUND", "message": "Recording not found" } }

Widerrufen Sie einen Schlüssel sofort, wenn er in falsche Hände geraten sein könnte.