Aufnahmen

Eine Aufnahme gibt es einmal je aufgezeichnetem Meeting. Diese Endpunkte listen Aufnahmen, liefern das Transkript als Daten oder als fertige Datei, liefern die Zusammenfassungen, legen neue Aufnahmen aus Uploads oder URLs an und setzen ihre Tags.

Jeder Endpunkt unten zeigt in der Mitte seine Parameter und Antwortfelder. Rechts findest du Anfragebeispiele in cURL, JavaScript und Python, eine Beispielantwort und Ausprobieren, das die Anfrage mit deinem eigenen Token wirklich abschickt.

Listet die Aufnahmen eines Unternehmenskontos auf (paginiert, optional nach Datum gefiltert)

GET/v1.0/directories/{directoryId}/recordingsAusprobieren →

Paginierung über ?page + ?pageSize (max. 100). Die optionalen Parameter ?createdAfter / ?createdBefore sind UTC ISO-8601 (YYYY-MM-DDTHH:MM:SSZ, siehe „Datum & Uhrzeit" oben). Absteigend nach Erstellungsdatum sortiert.

Feldübersicht aus der Spezifikation

Felder der Antwort:

page / pageSize / total / hasMore: Paginierungs-Hülle (aktuelle Seite, Seitengröße, Gesamtzahl, ob weitere Seiten folgen).
items (array): die Aufnahmen auf dieser Seite. Jeder Eintrag enthält:
- recordingId (string): Id der Aufnahme.
- name (string | null): Anzeigename der Aufnahme.
- durationInSeconds (number | null): Dauer in Sekunden.
- isManualUpload (boolean): true, wenn manuell hochgeladen (ohne Meeting-Bot).
- isTranscriptionSucceeded (boolean): true, wenn ein verwertbares Transkript existiert. Ein Durchlauf, der ohne Ergebnis beendet wurde (kein gesprochenes Audio, leere Datei, Sprache nicht erkannt), lässt diesen Wert auf false.
- isTranscriptionCompleted (boolean): true, sobald der Transkriptionsdurchlauf beendet ist, unabhängig davon, ob ein Transkript entstanden ist. Unterscheidet „läuft noch" von „ohne Ergebnis beendet".
- transcriptionCompletionReason (string enum): warum der Durchlauf beendet wurde. Einer von succeeded, noSpokenAudio, fileEmpty, languageNotDetected, error, quotaExceeded, unknown. Der zugrunde liegende Fehlertext wird bewusst nicht offengelegt.
- languageCode (string | null): Sprachcode der Aufnahme (IETF-Sprach-Tag, z. B. de-DE, en-US).
- createdOn (string): Zeitstempel der Erstellung (ISO-8601).
- tags (array): effektive Tags (eigene plus geerbte von verknüpften Terminen und deren Serienmaster). Jeder Tag enthält:
  - tagId (string): Id des Tags.
  - name (string): Anzeigename des Tags.
  - colorCode (string | null): ein Farbschlüssel aus der Sally-Tag-Palette (ein Farbname wie blue/red/green, kein roher Hex-Wert; vollständige Liste im Schema); null, wenn nicht gesetzt.

Pfadparameter

directoryIdstringPflicht
Id des Unternehmenskontos (des Sally-Firmenkontos), zu dem die Ressource gehört. Die Unternehmenskonten, die ein Token ansprechen kann, listet GET /v1.0/me/directories/memberships auf.

Query-Parameter

pagenumberoptional
Seitennummer, beginnend bei 1. Standard: 1.
pageSizenumberoptional
Einträge pro Seite. Standard: 25, maximal 100.
createdAfterstringoptional
Nur Aufnahmen, die zu oder nach diesem UTC-ISO-8601-Zeitstempel erstellt wurden (YYYY-MM-DDTHH:MM:SSZ).
createdBeforestringoptional
Nur Aufnahmen, die zu oder vor diesem UTC-ISO-8601-Zeitstempel erstellt wurden (YYYY-MM-DDTHH:MM:SSZ).
fieldsstringoptional
Kommagetrennte Liste der Felder, die zurückgegeben werden sollen. Lässt du den Parameter weg, bekommst du alle Felder, auch solche, die in Zukunft hinzukommen. Das ist deine Entscheidung: Nenne deine Felder explizit, wenn du davor geschützt sein willst.
Nur Felder der ersten Ebene können angegeben werden. Eine verschachtelte Liste wie attendees, tags oder sectionItems wird ganz oder gar nicht zurückgegeben; attendees.name wird nicht unterstützt.
Bei einer paginierten Antwort gilt die Auswahl für die Einträge in items; page, pageSize, total und hasMore werden immer zurückgegeben. Ein unbekannter Name wird mit 400 abgelehnt statt ignoriert.
Hier auswählbar: createdOn, durationInSeconds, isManualUpload, isTranscriptionCompleted, isTranscriptionSucceeded, languageCode, name, recordingId, tags, transcriptionCompletionReason.
Beispiel: createdOn,durationInSeconds

Antwort: je Eintrag in items

recordingIdstringPflicht
Id der Aufnahme.
namestringPflichtkann null sein
Anzeigename der Aufnahme.
durationInSecondsnumberPflichtkann null sein
Dauer in Sekunden.
isManualUploadbooleanPflicht
True, wenn manuell hochgeladen (ohne Meeting-Bot).
isTranscriptionSucceededbooleanPflicht
True, wenn ein verwertbares Transkript existiert. Das ist NICHT dasselbe wie ein beendeter Durchlauf: Auch eine Aufnahme ohne gesprochenes Audio wird beendet, und dann bleibt dieser Wert false.
isTranscriptionCompletedbooleanPflicht
True, sobald der Transkriptionsdurchlauf beendet ist, unabhängig davon, ob ein Transkript entstanden ist. Damit unterscheidest du "läuft noch" von "ohne Ergebnis beendet"; ob es etwas zu lesen gibt, sagt dir isTranscriptionSucceeded.
transcriptionCompletionReasonstringPflicht
Warum der Transkriptionsdurchlauf beendet wurde. unknown, solange er nicht beendet ist. Der zugrunde liegende Fehlertext wird bewusst nicht offengelegt.
Erlaubte Werte: succeedednoSpokenAudiofileEmptylanguageNotDetectederrorquotaExceededunknown
languageCodestringPflichtkann null sein
Sprachcode der Aufnahme (IETF-Sprach-Tag, z. B. de-DE, en-US).
createdOnstringPflicht
Zeitstempel der Erstellung (ISO-8601).
tagsobject[]Pflicht
Effektive Tags (eigene plus geerbte von verknüpften Terminen und deren Serienmaster).
3 Unterfelder
- tagIdstringPflicht
  Id des Tags.
- namestringPflicht
  Anzeigename des Tags.
- colorCodestringPflichtkann null sein
  Farbe des Tags als Schlüssel aus Sallys fester Tag-Palette: ein Farb-NAME, kein roher Hex-Wert. Einer von: indigo, purple, fuchsia, pink, rose, red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, slate, gray, zinc, stone, neutral. Der Client ordnet den Schlüssel der tatsächlichen Farbe (hell/dunkel) zu; null oder ein unbekannter Schlüssel wird in der neutralen Standardfarbe dargestellt. Null, wenn nicht gesetzt.

Jede Seite trägt außerdem page, pageSize, total, hasMore.

Statuscodes

200Erfolg
400
Ungültige Anfrage (Validierungsfehler).
401
Fehlender oder ungültiger Bearer-Token.
404
Ressource nicht gefunden oder nicht zugänglich.
429
Rate-Limit überschritten (pro Token/IP). Transkriptions-Uploads können außerdem den code FUP_LIMIT_EXCEEDED oder TOO_MANY_CONCURRENT_TRANSCRIPTIONS zurückgeben.
500
Interner Serverfehler.

Ausprobieren

Schick diese Anfrage wirklich ab, mit deinem eigenen Token und deinen eigenen Daten.

Anfrage

cURL
JavaScript
Python

curl "https://api.sally.io/v1.0/directories/$DIRECTORY_ID/recordings" \
  -H "Authorization: Bearer $SALLY_TOKEN"

const response = await fetch(`https://api.sally.io/v1.0/directories/${directoryId}/recordings`, {
  headers: {
    Authorization: `Bearer ${process.env.SALLY_TOKEN}`,
  },
});
const data = await response.json();

import os
import requests

response = requests.get(
    f"https://api.sally.io/v1.0/directories/{directory_id}/recordings",
    headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
)
data = response.json()

Beispielantwort 200 OK

{
  "page": 1,
  "pageSize": 25,
  "total": 137,
  "hasMore": true,
  "items": [
    {
      "recordingId": "53e2e041-4b34-41c7-a285-634d80b3675d",
      "name": "Weekly team meeting",
      "durationInSeconds": 1843,
      "isManualUpload": true,
      "isTranscriptionSucceeded": true,
      "isTranscriptionCompleted": true,
      "transcriptionCompletionReason": "succeeded",
      "languageCode": "de-DE",
      "createdOn": "2026-09-24T09:30:00Z",
      "tags": [
        {
          "tagId": "18063a7e-a82b-4972-a850-f866b8b4a046",
          "name": "Customer",
          "colorCode": "indigo"
        }
      ]
    }
  ]
}

Gibt eine einzelne Aufnahme zurück

GET/v1.0/directories/{directoryId}/recordings/{recordingId}Ausprobieren →

Feldübersicht aus der Spezifikation

Felder der Antwort:

recordingId (string): Id der Aufnahme.
name (string | null): Anzeigename der Aufnahme.
durationInSeconds (number | null): Dauer in Sekunden.
isManualUpload (boolean): true, wenn manuell hochgeladen (ohne Meeting-Bot).
isTranscriptionSucceeded (boolean): true, wenn ein verwertbares Transkript existiert. Ein Durchlauf, der ohne Ergebnis beendet wurde (kein gesprochenes Audio, leere Datei, Sprache nicht erkannt), lässt diesen Wert auf false.
isTranscriptionCompleted (boolean): true, sobald der Transkriptionsdurchlauf beendet ist, unabhängig davon, ob ein Transkript entstanden ist. Unterscheidet „läuft noch" von „ohne Ergebnis beendet".
transcriptionCompletionReason (string enum): warum der Durchlauf beendet wurde. Einer von succeeded, noSpokenAudio, fileEmpty, languageNotDetected, error, quotaExceeded, unknown. Der zugrunde liegende Fehlertext wird bewusst nicht offengelegt.
languageCode (string | null): Sprachcode der Aufnahme (IETF-Sprach-Tag, z. B. de-DE, en-US).
createdOn (string): Zeitstempel der Erstellung (ISO-8601).
tags (array): effektive Tags (eigene plus geerbte von verknüpften Terminen und deren Serienmaster). Jeder Tag enthält:
- tagId (string): Id des Tags.
- name (string): Anzeigename des Tags.
- colorCode (string | null): ein Farbschlüssel aus der Sally-Tag-Palette (ein Farbname wie blue/red/green, kein roher Hex-Wert; vollständige Liste im Schema); null, wenn nicht gesetzt.

Pfadparameter

directoryIdstringPflicht
Id des Unternehmenskontos (des Sally-Firmenkontos), zu dem die Ressource gehört. Die Unternehmenskonten, die ein Token ansprechen kann, listet GET /v1.0/me/directories/memberships auf.
recordingIdstringPflicht
Id der Aufnahme.

Query-Parameter

fieldsstringoptional
Kommagetrennte Liste der Felder, die zurückgegeben werden sollen. Lässt du den Parameter weg, bekommst du alle Felder, auch solche, die in Zukunft hinzukommen. Das ist deine Entscheidung: Nenne deine Felder explizit, wenn du davor geschützt sein willst.
Nur Felder der ersten Ebene können angegeben werden. Eine verschachtelte Liste wie attendees, tags oder sectionItems wird ganz oder gar nicht zurückgegeben; attendees.name wird nicht unterstützt.
Bei einer paginierten Antwort gilt die Auswahl für die Einträge in items; page, pageSize, total und hasMore werden immer zurückgegeben. Ein unbekannter Name wird mit 400 abgelehnt statt ignoriert.
Hier auswählbar: createdOn, durationInSeconds, isManualUpload, isTranscriptionCompleted, isTranscriptionSucceeded, languageCode, name, recordingId, tags, transcriptionCompletionReason.
Beispiel: createdOn,durationInSeconds

Antwort

recordingIdstringPflicht
Id der Aufnahme.
namestringPflichtkann null sein
Anzeigename der Aufnahme.
durationInSecondsnumberPflichtkann null sein
Dauer in Sekunden.
isManualUploadbooleanPflicht
True, wenn manuell hochgeladen (ohne Meeting-Bot).
isTranscriptionSucceededbooleanPflicht
True, wenn ein verwertbares Transkript existiert. Das ist NICHT dasselbe wie ein beendeter Durchlauf: Auch eine Aufnahme ohne gesprochenes Audio wird beendet, und dann bleibt dieser Wert false.
isTranscriptionCompletedbooleanPflicht
True, sobald der Transkriptionsdurchlauf beendet ist, unabhängig davon, ob ein Transkript entstanden ist. Damit unterscheidest du "läuft noch" von "ohne Ergebnis beendet"; ob es etwas zu lesen gibt, sagt dir isTranscriptionSucceeded.
transcriptionCompletionReasonstringPflicht
Warum der Transkriptionsdurchlauf beendet wurde. unknown, solange er nicht beendet ist. Der zugrunde liegende Fehlertext wird bewusst nicht offengelegt.
Erlaubte Werte: succeedednoSpokenAudiofileEmptylanguageNotDetectederrorquotaExceededunknown
languageCodestringPflichtkann null sein
Sprachcode der Aufnahme (IETF-Sprach-Tag, z. B. de-DE, en-US).
createdOnstringPflicht
Zeitstempel der Erstellung (ISO-8601).
tagsobject[]Pflicht
Effektive Tags (eigene plus geerbte von verknüpften Terminen und deren Serienmaster).
3 Unterfelder
- tagIdstringPflicht
  Id des Tags.
- namestringPflicht
  Anzeigename des Tags.
- colorCodestringPflichtkann null sein
  Farbe des Tags als Schlüssel aus Sallys fester Tag-Palette: ein Farb-NAME, kein roher Hex-Wert. Einer von: indigo, purple, fuchsia, pink, rose, red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, slate, gray, zinc, stone, neutral. Der Client ordnet den Schlüssel der tatsächlichen Farbe (hell/dunkel) zu; null oder ein unbekannter Schlüssel wird in der neutralen Standardfarbe dargestellt. Null, wenn nicht gesetzt.

Statuscodes

200Erfolg
400
Ungültige Anfrage (Validierungsfehler).
401
Fehlender oder ungültiger Bearer-Token.
404
Ressource nicht gefunden oder nicht zugänglich.
429
Rate-Limit überschritten (pro Token/IP). Transkriptions-Uploads können außerdem den code FUP_LIMIT_EXCEEDED oder TOO_MANY_CONCURRENT_TRANSCRIPTIONS zurückgeben.
500
Interner Serverfehler.

Ausprobieren

Schick diese Anfrage wirklich ab, mit deinem eigenen Token und deinen eigenen Daten.

Anfrage

cURL
JavaScript
Python

curl "https://api.sally.io/v1.0/directories/$DIRECTORY_ID/recordings/$RECORDING_ID" \
  -H "Authorization: Bearer $SALLY_TOKEN"

const response = await fetch(`https://api.sally.io/v1.0/directories/${directoryId}/recordings/${recordingId}`, {
  headers: {
    Authorization: `Bearer ${process.env.SALLY_TOKEN}`,
  },
});
const data = await response.json();

import os
import requests

response = requests.get(
    f"https://api.sally.io/v1.0/directories/{directory_id}/recordings/{recording_id}",
    headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
)
data = response.json()

Beispielantwort 200 OK

{
  "recordingId": "53e2e041-4b34-41c7-a285-634d80b3675d",
  "name": "Weekly team meeting",
  "durationInSeconds": 1843,
  "isManualUpload": true,
  "isTranscriptionSucceeded": true,
  "isTranscriptionCompleted": true,
  "transcriptionCompletionReason": "succeeded",
  "languageCode": "de-DE",
  "createdOn": "2026-09-24T09:30:00Z",
  "tags": [
    {
      "tagId": "18063a7e-a82b-4972-a850-f866b8b4a046",
      "name": "Customer",
      "colorCode": "indigo"
    }
  ]
}

Gibt das Transkript einer Aufnahme zurück (zeitcodierte Segmente plus Sprecher)

GET/v1.0/directories/{directoryId}/recordings/{recordingId}/transcriptionAusprobieren →

Feldübersicht aus der Spezifikation

Felder der Antwort:

recordingId (string): Id der zugehörigen Aufnahme.
speakers (array): Sprecher des Transkripts. Jeder Eintrag enthält:
- speakerId (string): Id des Transkript-Sprechers (wird von jedem Segment referenziert).
- speakerNumber (number): Sprechernummer.
- name (string | null): Name des Sprechers.
- emailAddress (string | null): E-Mail-Adresse des Sprechers.
segments (array): zeitcodierte Segmente. Jeder Eintrag enthält:
- speakerId (string): Sprecher-Id des Segments (verweist auf die Liste speakers oben).
- startTime (number): Startzeit in Sekunden.
- endTime (number): Endzeit in Sekunden.
- text (string | null): transkribierter Text des Segments.

Pfadparameter

directoryIdstringPflicht
Id des Unternehmenskontos (des Sally-Firmenkontos), zu dem die Ressource gehört. Die Unternehmenskonten, die ein Token ansprechen kann, listet GET /v1.0/me/directories/memberships auf.
recordingIdstringPflicht
Id der Aufnahme.

Query-Parameter

fieldsstringoptional
Kommagetrennte Liste der Felder, die zurückgegeben werden sollen. Lässt du den Parameter weg, bekommst du alle Felder, auch solche, die in Zukunft hinzukommen. Das ist deine Entscheidung: Nenne deine Felder explizit, wenn du davor geschützt sein willst.
Nur Felder der ersten Ebene können angegeben werden. Eine verschachtelte Liste wie attendees, tags oder sectionItems wird ganz oder gar nicht zurückgegeben; attendees.name wird nicht unterstützt.
Bei einer paginierten Antwort gilt die Auswahl für die Einträge in items; page, pageSize, total und hasMore werden immer zurückgegeben. Ein unbekannter Name wird mit 400 abgelehnt statt ignoriert.
Hier auswählbar: recordingId, segments, speakers.
Beispiel: recordingId,segments

Antwort

recordingIdstringPflicht
Id der zugehörigen Aufnahme.
speakersobject[]Pflicht
Sprecher des Transkripts.
4 Unterfelder
- speakerIdstringPflicht
  Id des Transkript-Sprechers.
- speakerNumbernumberPflicht
  Sprechernummer.
- namestringPflichtkann null sein
  Name des Sprechers.
- emailAddressstringPflichtkann null sein
  E-Mail-Adresse des Sprechers.
segmentsobject[]Pflicht
Zeitcodierte Segmente.
4 Unterfelder
- speakerIdstringPflicht
  Sprecher-Id des Segments.
- startTimenumberPflicht
  Startzeit in Sekunden.
- endTimenumberPflicht
  Endzeit in Sekunden.
- textstringPflichtkann null sein
  Transkribierter Text des Segments.

Statuscodes

200Erfolg
400
Ungültige Anfrage (Validierungsfehler).
401
Fehlender oder ungültiger Bearer-Token.
404
Ressource nicht gefunden oder nicht zugänglich.
429
Rate-Limit überschritten (pro Token/IP). Transkriptions-Uploads können außerdem den code FUP_LIMIT_EXCEEDED oder TOO_MANY_CONCURRENT_TRANSCRIPTIONS zurückgeben.
500
Interner Serverfehler.

Ausprobieren

Schick diese Anfrage wirklich ab, mit deinem eigenen Token und deinen eigenen Daten.

Anfrage

cURL
JavaScript
Python

curl "https://api.sally.io/v1.0/directories/$DIRECTORY_ID/recordings/$RECORDING_ID/transcription" \
  -H "Authorization: Bearer $SALLY_TOKEN"

const response = await fetch(`https://api.sally.io/v1.0/directories/${directoryId}/recordings/${recordingId}/transcription`, {
  headers: {
    Authorization: `Bearer ${process.env.SALLY_TOKEN}`,
  },
});
const data = await response.json();

import os
import requests

response = requests.get(
    f"https://api.sally.io/v1.0/directories/{directory_id}/recordings/{recording_id}/transcription",
    headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
)
data = response.json()

Beispielantwort 200 OK

{
  "recordingId": "53e2e041-4b34-41c7-a285-634d80b3675d",
  "speakers": [
    {
      "speakerId": "b16c2c6f-d9f5-4709-a27e-41a319410893",
      "speakerNumber": 1,
      "name": "Example",
      "emailAddress": "anna.berger@example.com"
    }
  ],
  "segments": [
    {
      "speakerId": "b16c2c6f-d9f5-4709-a27e-41a319410893",
      "startTime": 1,
      "endTime": 1,
      "text": "We agreed on the rollout plan for October."
    }
  ]
}

Gibt das Transkript einer Aufnahme als fertige Dokumentdatei zurück

GET/v1.0/directories/{directoryId}/recordings/{recordingId}/transcription/documentAusprobieren →

Gibt dieselbe Datei zurück, die die Sally-Weboberfläche für dieses Transkript herunterlädt: mit Branding, Logos, Kopf- und Fußzeile, Sprechern und Zeitstempeln. Die Datei wird bei der Anfrage erzeugt und direkt in der Antwort zurückgegeben; es gibt keinen Auftrag, der abgefragt werden muss.

Feldübersicht aus der Spezifikation

Pfadparameter:

directoryId (string): Id des Unternehmenskontos, zu dem die Aufnahme gehört.
recordingId (string): Id der Aufnahme.

Abfrageparameter:

format (string enum, Pflicht): einer der Werte pdf, docx, xlsx, txt, md, vtt, srt. vtt und srt sind Untertiteldateien ohne Kopfbereich.
languageCode (string enum, optional): einer der Werte de-DE, en-US, es-ES, fr-FR, it-IT, nl-NL, pl-PL; Standard ist die Sprache des Token-Inhabers.

Dieser Endpunkt unterstützt ?fields= nicht.

Pfadparameter

directoryIdstringPflicht
Id des Unternehmenskontos (des Sally-Firmenkontos), zu dem die Ressource gehört. Die Unternehmenskonten, die ein Token ansprechen kann, listet GET /v1.0/me/directories/memberships auf.
recordingIdstringPflicht
Id der Aufnahme.

Query-Parameter

formatstringPflicht
Dateiformat des Dokuments.
Erlaubte Werte: pdfdocxxlsxtxtmdvttsrt
languageCodestringoptional
IETF-Sprach-Tag für die Beschriftungen und das Datumsformat im Dokument, z. B. de-DE. Standard ist die Sprache des Token-Inhabers, genau wie in der Sally-Weboberfläche. Die Sprache des Inhalts ändert sich dadurch NICHT, und die Schrift richtet sich immer nach der Sprache der Aufnahme, sodass chinesische Schriftzeichen auch mit en-US-Beschriftungen lesbar bleiben.
Erlaubte Werte: de-DEen-USes-ESfr-FRit-ITnl-NLpl-PL

Statuscodes

200Die Datei selbst. `Content-Disposition` enthält den Dateinamen, den die Sally-Weboberfläche für denselben Download verwendet (ASCII in `filename`, UTF-8 in `filename*`).
400
format fehlt oder ist unbekannt, oder languageCode ist unbekannt. Der Body nennt die erlaubten Werte (code: UNKNOWN_DOCUMENT_FORMAT oder UNKNOWN_LANGUAGE_CODE).
401
Fehlender oder ungültiger Bearer-Token.
403
Das Unternehmenskonto hat diesen Download für seine Mitglieder gesperrt (code: TRANSCRIPT_DOWNLOAD_PREVENTED).
404
Die Quelle existiert nicht, gehört zu einem anderen Unternehmenskonto, oder der Aufrufer hat keinen Zugriff auf die zugrunde liegende Aufnahme.
409
Die Aufnahme hat noch kein Transkript (code: TRANSCRIPT_NOT_AVAILABLE).
429
Rate-Limit überschritten (pro Token/IP). Transkriptions-Uploads können außerdem den code FUP_LIMIT_EXCEEDED oder TOO_MANY_CONCURRENT_TRANSCRIPTIONS zurückgeben.
500
Interner Serverfehler.

Ausprobieren

Schick diese Anfrage wirklich ab, mit deinem eigenen Token und deinen eigenen Daten.

Anfrage

cURL
JavaScript
Python

curl "https://api.sally.io/v1.0/directories/$DIRECTORY_ID/recordings/$RECORDING_ID/transcription/document?format=pdf" \
  -H "Authorization: Bearer $SALLY_TOKEN" \
  -OJ

const response = await fetch(`https://api.sally.io/v1.0/directories/${directoryId}/recordings/${recordingId}/transcription/document?format=pdf`, {
  headers: {
    Authorization: `Bearer ${process.env.SALLY_TOKEN}`,
  },
});
const file = await response.blob();

import os
import requests

response = requests.get(
    f"https://api.sally.io/v1.0/directories/{directory_id}/recordings/{recording_id}/transcription/document?format=pdf",
    headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
)
content = response.content

Beispielantwort 200 OK

"string"

Gibt die Zusammenfassungen einer Aufnahme zurück

GET/v1.0/directories/{directoryId}/recordings/{recordingId}/summariesAusprobieren →

Mit ?includeDetails=true bettet jede Zusammenfassung zusätzlich ihre Abschnittseinträge ein (die strukturierten Ergebnisse des Meetingtemplates pro Abschnitt). Ohne den Parameter erhältst du nur die Texte der Zusammenfassungen. Eine einzelne Zusammenfassung anhand ihrer Id holst du über GET .../summaries/{recordingSummaryId}.

Feldübersicht aus der Spezifikation

Jeder Eintrag enthält:

recordingSummaryId (string): Id der Zusammenfassung.
recordingId (string): Id der zugehörigen Aufnahme.
appointmentId (string | null): Id des zugehörigen Termins (falls vorhanden).
languageCode (string | null): Sprachcode der Zusammenfassung (IETF-Sprach-Tag, z. B. de-DE, en-US).
summary (string | null): Text der Zusammenfassung.
isSummarizationCompleted (boolean): true, sobald der Zusammenfassungsdurchlauf beendet ist, unabhängig davon, ob er etwas erzeugt hat.
isSummarizationSucceeded (boolean): true, wenn es etwas zu lesen gibt: Text der Zusammenfassung oder mindestens ein Abschnittseintrag. Auch ein Durchlauf über eine Aufnahme ohne Transkript wird beendet, und dann bleibt dieser Wert false.
summarizationCompletionReason (string enum): warum der Durchlauf beendet wurde. Einer von succeeded, noTranscript, emptyResult, error, unknown. noTranscript ist ein erwartetes Ergebnis, kein Fehler. Der zugrunde liegende Fehlertext wird bewusst nicht offengelegt.
createdOn (string): Zeitstempel der Erstellung (ISO-8601).
sectionItems (array | null): die erzeugten Abschnittseinträge der Zusammenfassung (strukturierte Ergebnisse des Meetingtemplates pro Abschnitt). Null, sofern nicht geladen (nur mit ?includeDetails=true). Jeder Abschnittseintrag enthält:
- sectionItemId (string): Id des Abschnittseintrags.
- meetingTemplateSectionId (string | null): Id des Meetingtemplate-Abschnitts, aus dem dieser Eintrag erzeugt wurde (auflösen über GET /v1.0/directories/{directoryId}/meetingtemplates/{meetingTemplateId}); null bei abgeleiteten Einträgen (z. B. Aufgabeneinträge).
- title (string): Titel des Template-Abschnittseintrags.
- sectionType (string enum): Abschnittstyp des Eintrags. Einer von summary, tasks, topics, decisions, customList, freeText, unknown.
- outputFormat (string enum): Ausgabeformat des Eintragsinhalts. Einer von html, markdown, unknown.
- sortOrder (number): Reihenfolge innerhalb der Zusammenfassung.
- content (string | null): Freitext- bzw. Markdown-Inhalt des Eintrags.
- subject (string | null): Betreff der Aufgabe (bei aufgabenartigen Abschnittseinträgen).
- description (string | null): Beschreibung der Aufgabe.
- responsibleUserName (string | null): verantwortliche Person (Name).
- responsibleUserEmail (string | null): verantwortliche Person (E-Mail).
- dueDate (string | null): Fälligkeitsdatum (ISO-8601).

Pfadparameter

directoryIdstringPflicht
Id des Unternehmenskontos (des Sally-Firmenkontos), zu dem die Ressource gehört. Die Unternehmenskonten, die ein Token ansprechen kann, listet GET /v1.0/me/directories/memberships auf.
recordingIdstringPflicht
Id der Aufnahme.

Query-Parameter

includeDetailsbooleanoptional
Bei true enthält jede Zusammenfassung zusätzlich ihre sectionItems. Fehlt der Parameter oder ist er false, ist sectionItems null und nur der Text der Zusammenfassung wird zurückgegeben.
fieldsstringoptional
Kommagetrennte Liste der Felder, die zurückgegeben werden sollen. Lässt du den Parameter weg, bekommst du alle Felder, auch solche, die in Zukunft hinzukommen. Das ist deine Entscheidung: Nenne deine Felder explizit, wenn du davor geschützt sein willst.
Nur Felder der ersten Ebene können angegeben werden. Eine verschachtelte Liste wie attendees, tags oder sectionItems wird ganz oder gar nicht zurückgegeben; attendees.name wird nicht unterstützt.
Bei einer paginierten Antwort gilt die Auswahl für die Einträge in items; page, pageSize, total und hasMore werden immer zurückgegeben. Ein unbekannter Name wird mit 400 abgelehnt statt ignoriert.
Hier auswählbar: appointmentId, createdOn, isSummarizationCompleted, isSummarizationSucceeded, languageCode, recordingId, recordingSummaryId, sectionItems, summarizationCompletionReason, summary.
Beispiel: appointmentId,createdOn

Antwort

recordingSummaryIdstringPflicht
Id der Zusammenfassung.
recordingIdstringPflicht
Id der zugehörigen Aufnahme.
appointmentIdstringPflichtkann null sein
Id des zugehörigen Termins (falls vorhanden).
languageCodestringPflichtkann null sein
Sprachcode der Zusammenfassung (IETF-Sprach-Tag, z. B. de-DE, en-US).
summarystringPflichtkann null sein
Text der Zusammenfassung.
isSummarizationCompletedbooleanPflicht
True, sobald der Zusammenfassungsdurchlauf beendet ist, unabhängig davon, ob er etwas erzeugt hat.
isSummarizationSucceededbooleanPflicht
True, wenn es etwas zu lesen gibt: Text der Zusammenfassung oder mindestens ein Abschnittseintrag. Auch ein Durchlauf über eine Aufnahme ohne Transkript wird beendet, und dann bleibt dieser Wert false.
summarizationCompletionReasonstringPflicht
Warum der Zusammenfassungsdurchlauf beendet wurde. noTranscript bedeutet, dass es nichts zusammenzufassen gab; das ist ein erwartetes Ergebnis und kein Fehler. unknown, solange er nicht beendet ist. Der zugrunde liegende Fehlertext wird bewusst nicht offengelegt.
Erlaubte Werte: succeedednoTranscriptemptyResulterrorunknown
createdOnstringPflicht
Zeitstempel der Erstellung (ISO-8601).
sectionItemsobject[]Pflichtkann null sein
Die erzeugten Abschnittseinträge der Zusammenfassung (die strukturierten Ergebnisse des Meetingtemplates pro Abschnitt). Null, wenn nicht geladen (der Listen-Endpunkt der Aufnahmen füllt dieses Feld nur mit ?includeDetails=true); der Endpunkt für eine einzelne Zusammenfassung liefert es immer mit.
18 Unterfelder
- sectionItemIdstringPflicht
  Id des Abschnittseintrags.
- meetingTemplateSectionIdstringPflichtkann null sein
  Id des Meetingtemplate-Abschnitts, aus dem dieser Eintrag erzeugt wurde. Auflösen über GET /v1.0/directories/{directoryId}/meetingtemplates/{meetingTemplateId} (entspricht der meetingTemplateSectionId eines Abschnitts). Null bei abgeleiteten Einträgen ohne Template-Abschnitt (z. B. Aufgabeneinträge).
- titlestringPflicht
  Titel des Template-Abschnittseintrags.
- sectionTypestringPflicht
  Abschnittstyp des Eintrags.
  Erlaubte Werte: summarytaskstopicsdecisionscustomListfreeTexttableappointmentemailunknown
- outputFormatstringPflicht
  Ausgabeformat des Eintragsinhalts.
  Erlaubte Werte: htmlmarkdownunknown
- sortOrdernumberPflicht
  Reihenfolge innerhalb der Zusammenfassung.
- contentstringPflichtkann null sein
  Freitext- bzw. Markdown-Inhalt des Eintrags. Bei den Abschnittstypen, die ihr Ergebnis in eigenen Feldern ablegen (Tabelle, Termin, E-Mail), enthält er eine lesbare Markdown-Darstellung dieser Felder, sodass auch ein Client, der nur dieses eine Feld liest, den Abschnitt sieht. Die eigenen Felder werden unverändert daneben zurückgegeben.
- subjectstringPflichtkann null sein
  Betreff der Aufgabe (bei aufgabenartigen Abschnittseinträgen).
- descriptionstringPflichtkann null sein
  Beschreibung der Aufgabe.
- responsibleUserNamestringPflichtkann null sein
  Verantwortliche Person (Name).
- responsibleUserEmailstringPflichtkann null sein
  Verantwortliche Person (E-Mail).
- dueDatestringPflichtkann null sein
  Fälligkeitsdatum (ISO-8601).
- tableVariantstringPflichtkann null sein
  Nur bei sectionType: table. structured bedeutet, dass das Template die Spalten festgelegt hat und das Ergebnis in tableData steht. free bedeutet, dass Sally die Spalten selbst gewählt hat und das Ergebnis eine Markdown-Tabelle in content ist. Bei allen anderen Abschnittstypen null.
  Erlaubte Werte: freestructuredunknown
- tableDataanyPflichtkann null sein
  Das Tabellenergebnis, nur gesetzt bei sectionType: table mit tableVariant: structured. Bei tableVariant: free ist es null und die Tabelle steht als Markdown-Tabelle in content.
- followUpMeetingStartTimestringPflichtkann null sein
  Beginn des vorgeschlagenen Folgetermins als LOKALES Datum mit Uhrzeit OHNE Zeitzone (YYYY-MM-DDTHH:mm:ss, z. B. 2026-10-16T09:00:00). Bewusst kein UTC-Zeitpunkt: Vereinbart wurde im Meeting eine Uhrzeit (Donnerstag um neun), und eine Zeitzone würde diese Uhrzeit für jeden Leser in einer anderen Zone verschieben. Wende die Zeitzone der Beteiligten an. Nur gesetzt bei sectionType: appointment.
- followUpMeetingEndTimestringPflichtkann null sein
  Ende des vorgeschlagenen Folgetermins, im selben lokalen Zeitformat wie followUpMeetingStartTime. Null, wenn im Meeting ein Beginn, aber kein Ende genannt wurde.
- followUpMeetingParticipantsobject[]Pflichtkann null sein
  Die Personen, die im Meeting für den Folgetermin genannt wurden. Nur gesetzt bei sectionType: appointment.
  4 Unterfelder
  - userIdstringPflichtkann null sein
    Id des zugeordneten Nutzerkontos, oder null, wenn für diese Person kein Konto gefunden wurde. Auflösen über GET /v1.0/directories/{directoryId}/memberships/users/{userId}.
  - namestringPflicht
    Name der Person, wie er im Meeting erkannt wurde.
  - emailstringPflichtkann null sein
    E-Mail-Adresse, wie sie im Meeting erkannt wurde, in Kleinbuchstaben. Null, wenn die Person im Meeting ohne Adresse genannt wurde.
  - isExternalbooleanPflichtkann null sein
    True, wenn die Person als nicht zur eigenen Organisation gehörend erkannt wurde. Null, wenn das Meeting keinen Hinweis darauf gab.
- emailRecipientsobject[]Pflichtkann null sein
  Empfänger der vorgeschlagenen E-Mail, direkt und in Kopie (siehe kind). Nur gesetzt bei sectionType: email; der Betreff steht in subject, der Text in description.
  4 Unterfelder
  - userIdstringPflichtkann null sein
    Id des zugeordneten Nutzerkontos, oder null, wenn für diese Person kein Konto gefunden wurde. Auflösen über GET /v1.0/directories/{directoryId}/memberships/users/{userId}.
  - namestringPflicht
    Name der Person, wie er im Meeting erkannt wurde.
  - emailstringPflichtkann null sein
    E-Mail-Adresse, wie sie im Meeting erkannt wurde, in Kleinbuchstaben. Null, wenn die Person im Meeting ohne Adresse genannt wurde.
  - kindstringPflicht
    Ob die Person direkter Empfänger (to) oder in Kopie (cc) ist.
    Erlaubte Werte: tocc

Statuscodes

200Erfolg
400
Ungültige Anfrage (Validierungsfehler).
401
Fehlender oder ungültiger Bearer-Token.
404
Ressource nicht gefunden oder nicht zugänglich.
429
Rate-Limit überschritten (pro Token/IP). Transkriptions-Uploads können außerdem den code FUP_LIMIT_EXCEEDED oder TOO_MANY_CONCURRENT_TRANSCRIPTIONS zurückgeben.
500
Interner Serverfehler.

Ausprobieren

Schick diese Anfrage wirklich ab, mit deinem eigenen Token und deinen eigenen Daten.

Anfrage

cURL
JavaScript
Python

curl "https://api.sally.io/v1.0/directories/$DIRECTORY_ID/recordings/$RECORDING_ID/summaries" \
  -H "Authorization: Bearer $SALLY_TOKEN"

const response = await fetch(`https://api.sally.io/v1.0/directories/${directoryId}/recordings/${recordingId}/summaries`, {
  headers: {
    Authorization: `Bearer ${process.env.SALLY_TOKEN}`,
  },
});
const data = await response.json();

import os
import requests

response = requests.get(
    f"https://api.sally.io/v1.0/directories/{directory_id}/recordings/{recording_id}/summaries",
    headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
)
data = response.json()

Beispielantwort 200 OK

[
  {
    "recordingSummaryId": "731180f9-257a-46cf-a7e3-8ca508fb9c35",
    "recordingId": "53e2e041-4b34-41c7-a285-634d80b3675d",
    "appointmentId": "d4398f97-cd92-4d21-a6ec-4aab0a85441b",
    "languageCode": "de-DE",
    "summary": "string",
    "isSummarizationCompleted": true,
    "isSummarizationSucceeded": true,
    "summarizationCompletionReason": "succeeded",
    "createdOn": "2026-09-24T09:30:00Z",
    "sectionItems": [
      {
        "sectionItemId": "39ec96ee-9578-4082-a103-aa168fcd18f6",
        "meetingTemplateSectionId": "0ba1ea56-516d-485a-a738-e65e51578bbe",
        "title": "string",
        "sectionType": "summary",
        "outputFormat": "html",
        "sortOrder": 1,
        "content": "We agreed on the rollout plan for October.",
        "subject": "Quarterly planning",
        "description": "string",
        "responsibleUserName": "string",
        "responsibleUserEmail": "anna.berger@example.com",
        "dueDate": "2026-09-24T09:30:00Z",
        "tableVariant": "free",
        "tableData": null,
        "followUpMeetingStartTime": "string",
        "followUpMeetingEndTime": "string",
        "followUpMeetingParticipants": [
          {}
        ],
        "emailRecipients": [
          {}
        ]
      }
    ]
  }
]

Startet einen Aufnahme-Upload (Schritt 1/2) und gibt eine SAS-PUT-URL zurück

POST/v1.0/directories/{directoryId}/recordings/uploadsAusprobieren →

Anschließend lädt der Client die Datei-Bytes per PUT direkt zur zurückgegebenen uploadUrl hoch (mit den requiredHeaders) und ruft danach POST .../uploads/{uploadId}/finalize auf. Das Transkriptionskontingent (Fair-Usage-Regel) wird bereits hier geprüft: Ist das Kontingent erschöpft, wird 429 mit dem Code FUP_LIMIT_EXCEEDED zurückgegeben.

Feldübersicht aus der Spezifikation

Felder im Body:

fileName (string, Pflicht): ursprünglicher Dateiname (inkl. Dateiendung, zur Ableitung von MIME-Typ bzw. Endung).
mimeType (string, Pflicht): MIME-Typ der Datei (Whitelist: Video mp4/mkv/avi/mov/webm, Audio mp3/wav/flac/ogg/amr/m4a/opus/aac).
sizeBytes (number, Pflicht): Dateigröße in Bytes (> 0, max. 5 GB).

Pfadparameter

directoryIdstringPflicht
Id des Unternehmenskontos (des Sally-Firmenkontos), zu dem die Ressource gehört. Die Unternehmenskonten, die ein Token ansprechen kann, listet GET /v1.0/me/directories/memberships auf.

Query-Parameter

fieldsstringoptional
Kommagetrennte Liste der Felder, die zurückgegeben werden sollen. Lässt du den Parameter weg, bekommst du alle Felder, auch solche, die in Zukunft hinzukommen. Das ist deine Entscheidung: Nenne deine Felder explizit, wenn du davor geschützt sein willst.
Nur Felder der ersten Ebene können angegeben werden. Eine verschachtelte Liste wie attendees, tags oder sectionItems wird ganz oder gar nicht zurückgegeben; attendees.name wird nicht unterstützt.
Bei einer paginierten Antwort gilt die Auswahl für die Einträge in items; page, pageSize, total und hasMore werden immer zurückgegeben. Ein unbekannter Name wird mit 400 abgelehnt statt ignoriert.
Hier auswählbar: maxBytes, requiredHeaders, storageMode, uploadId, uploadUrl.
Beispiel: maxBytes,requiredHeaders

Request-Body application/json

fileNamestringPflicht
Ursprünglicher Dateiname (inkl. Dateiendung, zur Ableitung von MIME-Typ bzw. Endung).
mimeTypestringPflicht
MIME-Typ der Datei (Whitelist: Video mp4/mkv/avi/mov/webm, Audio mp3/wav/flac/ogg/amr/m4a/opus/aac).
Beispiel: audio/mpeg
sizeBytesnumberPflicht
Dateigröße in Bytes (> 0, max. 5 GB).

Antwort

uploadIdstringPflicht
Upload-Token, wird im Abschluss-Schritt mitgegeben.
uploadUrlstringPflicht
Absolute Azure-SAS-URL. Der Client lädt die Datei-Bytes per PUT direkt dorthin hoch (ohne Umweg über die API).
storageModestringPflicht
Speichermodus.
Beispiel: azure-blob
requiredHeadersobjectPflicht
Header, die beim PUT mitgesendet werden müssen.
Beispiel: {"x-ms-blob-type":"BlockBlob"}
maxBytesnumberPflicht
Maximal erlaubte Upload-Größe in Bytes.

Statuscodes

200Erfolg
400
Ungültige Anfrage (Validierungsfehler).
401
Fehlender oder ungültiger Bearer-Token.
403
Verboten (unzureichende Berechtigungen).
404
Ressource nicht gefunden oder nicht zugänglich.
429
Rate-Limit überschritten (pro Token/IP). Transkriptions-Uploads können außerdem den code FUP_LIMIT_EXCEEDED oder TOO_MANY_CONCURRENT_TRANSCRIPTIONS zurückgeben.
500
Interner Serverfehler.

Ausprobieren

Schick diese Anfrage wirklich ab, mit deinem eigenen Token und deinen eigenen Daten.

Anfrage

cURL
JavaScript
Python

curl -X POST "https://api.sally.io/v1.0/directories/$DIRECTORY_ID/recordings/uploads" \
  -H "Authorization: Bearer $SALLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "fileName": "string",
  "mimeType": "audio/mpeg",
  "sizeBytes": 184320000
}'

const response = await fetch(`https://api.sally.io/v1.0/directories/${directoryId}/recordings/uploads`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SALLY_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "fileName": "string",
    "mimeType": "audio/mpeg",
    "sizeBytes": 184320000
  }),
});
const data = await response.json();

import os
import requests

response = requests.post(
    f"https://api.sally.io/v1.0/directories/{directory_id}/recordings/uploads",
    headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
    json={
        "fileName": "string",
        "mimeType": "audio/mpeg",
        "sizeBytes": 184320000,
    },
)
data = response.json()

Beispielantwort 200 OK

{
  "uploadId": "2054a871-e250-4b17-a44c-8dbda99714cd",
  "uploadUrl": "https://example.com/hooks/sally",
  "storageMode": "azure-blob",
  "requiredHeaders": {
    "x-ms-blob-type": "BlockBlob"
  },
  "maxBytes": 1
}

Schließt einen Aufnahme-Upload ab (Schritt 2/2) und erstellt die Aufnahme

POST/v1.0/directories/{directoryId}/recordings/uploads/{uploadId}/finalizeAusprobieren →

Rufe diesen Endpunkt nach einem erfolgreichen PUT der Datei-Bytes auf. Er prüft den Blob, legt den Datensatz der Aufnahme an und startet die Transkriptions-Pipeline. Gibt die recordingId zurück. Laufen zu viele Transkriptionen des Unternehmenskontos gleichzeitig, wird 429 mit dem Code TOO_MANY_CONCURRENT_TRANSCRIPTIONS zurückgegeben.

Feldübersicht aus der Spezifikation

Felder im Body (alle optional):

languageCode (string, optional): Sprachcode des Audios (IETF-Sprach-Tag, z. B. de-DE, en-US). Weglassen oder null für automatische Erkennung.
speakerCount (number, optional): Anzahl der Sprecher (für die Sprechertrennung).
appointmentId (string, optional): optional verknüpfter Termin (GUID).
choice (copy | replace, optional): nur, wenn der verknüpfte Termin bereits eine aktive Aufnahme hat. Ohne diesen Wert schlägt ein solcher Upload mit 409 und dem Code RECORDING_EXISTS_CHOICE_REQUIRED fehl; die hochgeladene Datei bleibt erhalten und der Aufruf kann mit einer Auswahl wiederholt werden.

Pfadparameter

directoryIdstringPflicht
Id des Unternehmenskontos (des Sally-Firmenkontos), zu dem die Ressource gehört. Die Unternehmenskonten, die ein Token ansprechen kann, listet GET /v1.0/me/directories/memberships auf.
uploadIdstringPflicht
Id des Uploads.

Query-Parameter

fieldsstringoptional
Kommagetrennte Liste der Felder, die zurückgegeben werden sollen. Lässt du den Parameter weg, bekommst du alle Felder, auch solche, die in Zukunft hinzukommen. Das ist deine Entscheidung: Nenne deine Felder explizit, wenn du davor geschützt sein willst.
Nur Felder der ersten Ebene können angegeben werden. Eine verschachtelte Liste wie attendees, tags oder sectionItems wird ganz oder gar nicht zurückgegeben; attendees.name wird nicht unterstützt.
Bei einer paginierten Antwort gilt die Auswahl für die Einträge in items; page, pageSize, total und hasMore werden immer zurückgegeben. Ein unbekannter Name wird mit 400 abgelehnt statt ignoriert.
Hier auswählbar: recordingId.
Beispiel: recordingId

Request-Body application/json

languageCodestringoptionalkann null sein
Sprachcode des Audios (IETF-Sprach-Tag, z. B. de-DE, en-US). Weglassen oder null für automatische Erkennung.
speakerCountnumberoptionalkann null sein
Anzahl der Sprecher (für die Sprechertrennung).
appointmentIdstringoptionalkann null sein
Optional verknüpfter Termin (GUID).
choicestringoptionalkann null sein
Nur nötig, wenn der verknüpfte Termin bereits eine aktive Aufnahme hat; sonst ignoriert. copy legt für den hochladenden Nutzer eine Kopie des Termins an und hängt die Datei dort an, die bestehende Aufnahme bleibt am ursprünglichen Termin. replace hängt die Datei an den Termin und entfernt die bestehende Aufnahme, sobald die neue angelegt ist. Ohne diesen Wert schlägt ein Upload zu einem Termin, der bereits eine Aufnahme hat, mit 409 und dem Code RECORDING_EXISTS_CHOICE_REQUIRED fehl.
Erlaubte Werte: copyreplace

Antwort

recordingIdstringPflicht
Id der erstellten Aufnahme (die Transkription wurde gestartet).

Statuscodes

200Erfolg
400
Ungültige Anfrage (Validierungsfehler).
401
Fehlender oder ungültiger Bearer-Token.
403
Verboten (unzureichende Berechtigungen).
404
Ressource nicht gefunden oder nicht zugänglich.
429
Rate-Limit überschritten (pro Token/IP). Transkriptions-Uploads können außerdem den code FUP_LIMIT_EXCEEDED oder TOO_MANY_CONCURRENT_TRANSCRIPTIONS zurückgeben.
500
Interner Serverfehler.

Ausprobieren

Schick diese Anfrage wirklich ab, mit deinem eigenen Token und deinen eigenen Daten.

Anfrage

cURL
JavaScript
Python

curl -X POST "https://api.sally.io/v1.0/directories/$DIRECTORY_ID/recordings/uploads/$UPLOAD_ID/finalize" \
  -H "Authorization: Bearer $SALLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "languageCode": "de-DE",
  "speakerCount": 2,
  "appointmentId": "d4398f97-cd92-4d21-a6ec-4aab0a85441b",
  "choice": "copy"
}'

const response = await fetch(`https://api.sally.io/v1.0/directories/${directoryId}/recordings/uploads/${uploadId}/finalize`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SALLY_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "languageCode": "de-DE",
    "speakerCount": 2,
    "appointmentId": "d4398f97-cd92-4d21-a6ec-4aab0a85441b",
    "choice": "copy"
  }),
});
const data = await response.json();

import os
import requests

response = requests.post(
    f"https://api.sally.io/v1.0/directories/{directory_id}/recordings/uploads/{upload_id}/finalize",
    headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
    json={
        "languageCode": "de-DE",
        "speakerCount": 2,
        "appointmentId": "d4398f97-cd92-4d21-a6ec-4aab0a85441b",
        "choice": "copy",
    },
)
data = response.json()

Beispielantwort 200 OK

{
  "recordingId": "53e2e041-4b34-41c7-a285-634d80b3675d"
}

Erstellt eine Aufnahme aus einer Datei-URL (kein Upload nötig)

POST/v1.0/directories/{directoryId}/recordings/from-urlAusprobieren →

Sally lädt die Datei serverseitig von der URL, speichert sie und startet die Transkriptions- und Zusammenfassungs-Pipeline, genau wie bei einem abgeschlossenen Upload. Nutze diesen Weg statt des zweistufigen Uploads, wenn die Datei bereits über https erreichbar ist. Der Aufruf kehrt zurück, sobald die Datei geladen wurde und die Aufnahme existiert; die Transkription läuft dann im Hintergrund. Frage für das Ergebnis also GET .../recordings/{recordingId} ab oder nutze einen Webhook.

Feldübersicht aus der Spezifikation

Welche Bedingungen die URL erfüllen muss (jede davon wird durchgesetzt, ein Verstoß liefert 400):

Nur https. Kein http, kein anderes Schema.
Keine Zugangsdaten in der URL. Eine Form wie user:pass@host wird abgelehnt.
Nur öffentliche Ziele. Der Host wird aufgelöst und abgelehnt, wenn er in ein privates oder reserviertes Netz zeigt (Loopback, private Bereiche, Link-Local einschließlich Cloud-Metadaten, CGNAT, Multicast). Die geprüfte Adresse wird dann für die Verbindung fixiert, sodass eine DNS-Antwort, die sich zwischen Prüfung und Abruf ändert, uns nicht nach innen umleiten kann.
Keine Weiterleitungen. Übergib die endgültige Adresse; eine Weiterleitung wird abgelehnt statt verfolgt.
Ein unterstützter Medientyp, entweder über Content-Type oder über die Dateiendung: mp4, mkv, avi, mov, webm, mp3, wav, flac, ogg, amr, m4a, opus, aac.
Größenlimit wie vom Upload-Endpunkt zurückgegeben (maxBytes). Geprüft werden sowohl die angegebene Content-Length als auch die tatsächlichen Bytes.

Es gelten dieselben Lizenz-, Test- und Fair-Usage-Regeln wie bei einem Upload. Laufen zu viele Transkriptionen des Unternehmenskontos gleichzeitig, wird 429 mit dem Code TOO_MANY_CONCURRENT_TRANSCRIPTIONS zurückgegeben und nichts geladen.

Felder im Body:

url (string): die https-URL der Datei.
name (string, optional): Name der Aufnahme. Die URL wird nie als Name verwendet, weil Presigned Links Zugangsdaten in ihrem Query-String enthalten.
languageCode (string, optional): IETF-Sprach-Tag des Audios, z. B. de-DE. Weglassen für automatische Erkennung.
speakerCount (number, optional): Anzahl der Sprecher, für die Sprechertrennung.

Pfadparameter

directoryIdstringPflicht
Id des Unternehmenskontos (des Sally-Firmenkontos), zu dem die Ressource gehört. Die Unternehmenskonten, die ein Token ansprechen kann, listet GET /v1.0/me/directories/memberships auf.

Query-Parameter

fieldsstringoptional
Kommagetrennte Liste der Felder, die zurückgegeben werden sollen. Lässt du den Parameter weg, bekommst du alle Felder, auch solche, die in Zukunft hinzukommen. Das ist deine Entscheidung: Nenne deine Felder explizit, wenn du davor geschützt sein willst.
Nur Felder der ersten Ebene können angegeben werden. Eine verschachtelte Liste wie attendees, tags oder sectionItems wird ganz oder gar nicht zurückgegeben; attendees.name wird nicht unterstützt.
Bei einer paginierten Antwort gilt die Auswahl für die Einträge in items; page, pageSize, total und hasMore werden immer zurückgegeben. Ein unbekannter Name wird mit 400 abgelehnt statt ignoriert.
Hier auswählbar: recordingId.
Beispiel: recordingId

Request-Body application/json

urlstringPflicht
Öffentlich erreichbare https-URL der Audio- oder Videodatei. Die URL muss auf die Datei selbst zeigen, nicht auf eine Landingpage oder eine Weiterleitung. Presigned Links (S3, Azure Blob, Google Cloud Storage) funktionieren, solange sie zum Zeitpunkt des Aufrufs gültig sind.
namestringoptionalkann null sein
Name der Aufnahme. Wird er weggelassen, wird ein Name generiert; die URL wird nie als Name verwendet, da Presigned Links Zugangsdaten in ihrem Query-String enthalten.
languageCodestringoptionalkann null sein
Sprachcode des Audios (IETF-Sprach-Tag, z. B. de-DE, en-US). Weglassen oder null für automatische Erkennung.
speakerCountnumberoptionalkann null sein
Anzahl der Sprecher (für die Sprechertrennung).

Antwort

recordingIdstringPflicht
Id der erstellten Aufnahme (die Transkription wurde gestartet).

Statuscodes

200Erfolg
400
Ungültige Anfrage (Validierungsfehler).
401
Fehlender oder ungültiger Bearer-Token.
403
Verboten (unzureichende Berechtigungen).
404
Ressource nicht gefunden oder nicht zugänglich.
429
Rate-Limit überschritten (pro Token/IP). Transkriptions-Uploads können außerdem den code FUP_LIMIT_EXCEEDED oder TOO_MANY_CONCURRENT_TRANSCRIPTIONS zurückgeben.
500
Interner Serverfehler.

Ausprobieren

Schick diese Anfrage wirklich ab, mit deinem eigenen Token und deinen eigenen Daten.

Anfrage

cURL
JavaScript
Python

curl -X POST "https://api.sally.io/v1.0/directories/$DIRECTORY_ID/recordings/from-url" \
  -H "Authorization: Bearer $SALLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/hooks/sally"
}'

const response = await fetch(`https://api.sally.io/v1.0/directories/${directoryId}/recordings/from-url`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SALLY_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "url": "https://example.com/hooks/sally"
  }),
});
const data = await response.json();

import os
import requests

response = requests.post(
    f"https://api.sally.io/v1.0/directories/{directory_id}/recordings/from-url",
    headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
    json={
        "url": "https://example.com/hooks/sally",
    },
)
data = response.json()

Beispielantwort 200 OK

{
  "recordingId": "53e2e041-4b34-41c7-a285-634d80b3675d"
}

Ersetzt die direkten Tags einer Aufnahme (zuweisen/entfernen)

PUT/v1.0/directories/{directoryId}/recordings/{recordingId}/tagsAusprobieren →

Vollständiges Ersetzen der DIREKTEN Tags der Aufnahme; von verknüpften Terminen bzw. Terminserien geerbte Tags bleiben dynamisch. Maximal 20 direkte Tags pro Aufnahme.

Feldübersicht aus der Spezifikation

Felder im Body:

tagIds (array of strings): Ids bestehender Tags, die zugewiesen werden sollen; die angegebene Menge ersetzt die aktuelle. Zuweisen funktioniert nur mit Tag-Ids, lege den Tag also zuerst über POST /v1.0/directories/{directoryId}/tags an und weise ihn dann hier zu.

Pfadparameter

directoryIdstringPflicht
Id des Unternehmenskontos (des Sally-Firmenkontos), zu dem die Ressource gehört. Die Unternehmenskonten, die ein Token ansprechen kann, listet GET /v1.0/me/directories/memberships auf.
recordingIdstringPflicht
Id der Aufnahme.

Query-Parameter

fieldsstringoptional
Kommagetrennte Liste der Felder, die zurückgegeben werden sollen. Lässt du den Parameter weg, bekommst du alle Felder, auch solche, die in Zukunft hinzukommen. Das ist deine Entscheidung: Nenne deine Felder explizit, wenn du davor geschützt sein willst.
Nur Felder der ersten Ebene können angegeben werden. Eine verschachtelte Liste wie attendees, tags oder sectionItems wird ganz oder gar nicht zurückgegeben; attendees.name wird nicht unterstützt.
Bei einer paginierten Antwort gilt die Auswahl für die Einträge in items; page, pageSize, total und hasMore werden immer zurückgegeben. Ein unbekannter Name wird mit 400 abgelehnt statt ignoriert.
Hier auswählbar: colorCode, name, tagId.
Beispiel: colorCode,name

Request-Body application/json

tagIdsstring[]optional
Ids bestehender Tags, die zugewiesen werden sollen; die angegebene Menge ersetzt die aktuelle.

Antwort

tagIdstringPflicht
Id des Tags.
namestringPflicht
Anzeigename des Tags.
colorCodestringPflichtkann null sein
Farbe des Tags als Schlüssel aus Sallys fester Tag-Palette: ein Farb-NAME, kein roher Hex-Wert. Einer von: indigo, purple, fuchsia, pink, rose, red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, slate, gray, zinc, stone, neutral. Der Client ordnet den Schlüssel der tatsächlichen Farbe (hell/dunkel) zu; null oder ein unbekannter Schlüssel wird in der neutralen Standardfarbe dargestellt. Null, wenn nicht gesetzt.

Statuscodes

200Erfolg
400
Ungültige Anfrage (Validierungsfehler).
401
Fehlender oder ungültiger Bearer-Token.
403
Verboten (unzureichende Berechtigungen).
404
Ressource nicht gefunden oder nicht zugänglich.
429
Rate-Limit überschritten (pro Token/IP). Transkriptions-Uploads können außerdem den code FUP_LIMIT_EXCEEDED oder TOO_MANY_CONCURRENT_TRANSCRIPTIONS zurückgeben.
500
Interner Serverfehler.

Ausprobieren

Schick diese Anfrage wirklich ab, mit deinem eigenen Token und deinen eigenen Daten.

Anfrage

cURL
JavaScript
Python

curl -X PUT "https://api.sally.io/v1.0/directories/$DIRECTORY_ID/recordings/$RECORDING_ID/tags" \
  -H "Authorization: Bearer $SALLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "tagIds": [
    "18063a7e-a82b-4972-a850-f866b8b4a046"
  ]
}'

const response = await fetch(`https://api.sally.io/v1.0/directories/${directoryId}/recordings/${recordingId}/tags`, {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.SALLY_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "tagIds": [
      "18063a7e-a82b-4972-a850-f866b8b4a046"
    ]
  }),
});
const data = await response.json();

import os
import requests

response = requests.put(
    f"https://api.sally.io/v1.0/directories/{directory_id}/recordings/{recording_id}/tags",
    headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
    json={
        "tagIds": [
            "18063a7e-a82b-4972-a850-f866b8b4a046",
        ],
    },
)
data = response.json()

Beispielantwort 200 OK

[
  {
    "tagId": "18063a7e-a82b-4972-a850-f866b8b4a046",
    "name": "Customer",
    "colorCode": "indigo"
  }
]

Listet die Aufnahmen eines Unternehmenskontos auf (paginiert, optional nach Datum gefiltert)​

Pfadparameter

Query-Parameter

Antwort: je Eintrag in items

Statuscodes

Gibt eine einzelne Aufnahme zurück​

Pfadparameter

Query-Parameter

Antwort

Statuscodes

Gibt das Transkript einer Aufnahme zurück (zeitcodierte Segmente plus Sprecher)​

Pfadparameter

Query-Parameter

Antwort

Statuscodes

Gibt das Transkript einer Aufnahme als fertige Dokumentdatei zurück​

Pfadparameter

Query-Parameter

Statuscodes

Gibt die Zusammenfassungen einer Aufnahme zurück​

Pfadparameter

Query-Parameter

Antwort

Statuscodes

Startet einen Aufnahme-Upload (Schritt 1/2) und gibt eine SAS-PUT-URL zurück​

Pfadparameter

Query-Parameter

Request-Body application/json

Antwort

Statuscodes

Schließt einen Aufnahme-Upload ab (Schritt 2/2) und erstellt die Aufnahme​

Pfadparameter

Query-Parameter

Request-Body application/json

Antwort

Statuscodes

Erstellt eine Aufnahme aus einer Datei-URL (kein Upload nötig)​

Pfadparameter

Query-Parameter

Request-Body application/json

Antwort

Statuscodes

Ersetzt die direkten Tags einer Aufnahme (zuweisen/entfernen)​

Pfadparameter

Query-Parameter

Request-Body application/json

Antwort

Statuscodes

Listet die Aufnahmen eines Unternehmenskontos auf (paginiert, optional nach Datum gefiltert)

Gibt eine einzelne Aufnahme zurück

Gibt das Transkript einer Aufnahme zurück (zeitcodierte Segmente plus Sprecher)

Gibt das Transkript einer Aufnahme als fertige Dokumentdatei zurück

Gibt die Zusammenfassungen einer Aufnahme zurück

Startet einen Aufnahme-Upload (Schritt 1/2) und gibt eine SAS-PUT-URL zurück

Schließt einen Aufnahme-Upload ab (Schritt 2/2) und erstellt die Aufnahme

Erstellt eine Aufnahme aus einer Datei-URL (kein Upload nötig)

Ersetzt die direkten Tags einer Aufnahme (zuweisen/entfernen)