Wie du nur die Felder abrufst, die du brauchst

Jede Antwort der Sally API lässt sich mit ?fields= auf die Felder reduzieren, die du wirklich brauchst. Das hält Antworten klein und schützt deine Anbindung vor Feldern, die später hinzukommen.

Diese Seite zeigt den Parameter in einer Anfrage, die Regeln, nach denen er arbeitet, was bei einem Tippfehler passiert und wo das Weglassen eines einzigen Felds am meisten spart. Jedes Beispiel funktioniert so, wie es dasteht, sobald SALLY_TOKEN und DIRECTORY_ID gesetzt sind, siehe Schnellstart.

Schnellnavigation

Felder auswählen
Die Regeln
Unbekannte Namen werden abgelehnt
Wo es sich lohnt

1. Felder auswählen

fields ist ein Query-Parameter mit einer kommagetrennten Liste von Feldnamen:

Parameter	Typ	Standard	Beschreibung
`fields`	string	alle Felder	Kommagetrennte Feldnamen der ersten Ebene, etwa `recordingId,name,createdOn`.

Diese Anfrage listet Aufnahmen mit je drei Feldern:

cURL
JavaScript
Python

curl "https://api.sally.io/v1.0/directories/$DIRECTORY_ID/recordings?fields=recordingId,name,createdOn" \
  -H "Authorization: Bearer $SALLY_TOKEN"

const url = new URL(`https://api.sally.io/v1.0/directories/${directoryId}/recordings`);
url.searchParams.set('fields', ['recordingId', 'name', 'createdOn'].join(','));

const response = await fetch(url, {
  headers: {Authorization: `Bearer ${process.env.SALLY_TOKEN}`},
});
const {items} = await response.json();

import os
import requests

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

Jeder Eintrag trägt jetzt nur noch die genannten Felder, die Hülle bleibt vollständig:

200 OK
{
  "page": 1,
  "pageSize": 25,
  "total": 137,
  "hasMore": true,
  "items": [
    {
      "recordingId": "53e2e041-4b34-41c7-a285-634d80b3675d",
      "name": "Wöchentliches Teammeeting",
      "createdOn": "2026-09-24T09:30:00Z"
    }
  ]
}

Derselbe Eintrag mit und ohne Parameter:

Ohne `fields`	Mit `fields=recordingId,name,createdOn`
`recordingId`, `name`, `durationInSeconds`, `isManualUpload`, `isTranscriptionSucceeded`, `isTranscriptionCompleted`, `transcriptionCompletionReason`, `languageCode`, `createdOn`, `tags`	`recordingId`, `name`, `createdOn`
Später hinzukommende Felder erscheinen automatisch.	Später hinzukommende Felder erscheinen nicht.

2. Die Regeln

Ohne Angabe bekommst du alle Felder, auch solche, die in Zukunft hinzukommen. Wer seine Felder nennt, schützt sich davor.
Nur Namen der ersten Ebene. Eine verschachtelte Liste wie attendees, tags, segments oder sectionItems kommt ganz oder gar nicht. attendees.name wird nicht unterstützt.
Bei einer seitenweisen Antwort wirkt die Auswahl auf die Einträge in items. Die Hülle aus Paginierung und Suche (page, pageSize, total, hasMore) kommt immer mit.
Ein unbekannter Name wird mit 400 abgelehnt, statt still ignoriert zu werden. Ein Tippfehler scheitert damit laut, statt leise eine halbe Antwort zu liefern.
Fast jeder Endpunkt nimmt ihn an. Nur Endpunkte ohne JSON in der Antwort, etwa Löschungen und Datei-Downloads, sowie der Health Check haben keinen Parameter fields.

Wert von `fields`	Ergebnis
(weggelassen)	Alle Felder, auch künftige.
`recordingId,name`	Genau diese zwei Felder je Eintrag.
`tags`	Die ganze Liste `tags` mit allen Unterfeldern.
`tags.name`	Nicht unterstützt, verschachtelte Namen lassen sich nicht auswählen.
`recordingId,nmae`	400, `nmae` ist kein Feld.

3. Unbekannte Namen werden abgelehnt

Ein falsch geschriebener oder nicht unterstützter Name wird mit 400 und dem einheitlichen Fehler-Body beantwortet:

400 Bad Request
{
  "statusCode": 400,
  "message": "<für Menschen lesbare Beschreibung des Problems>"
}

Der Wortlaut von message ist für Menschen gedacht und kann sich ändern. Welche Namen ein Endpunkt annimmt, steht in der Referenz beim Parameter fields. Schau dort nach, wenn eine Auswahl scheitert.

4. Wo es sich lohnt

Ergebnis

Ein Transkript besteht fast nur aus segments, eine Zusammenfassung mit Details fast nur aus sectionItems. Lässt du eines davon weg, wird die Antwort deutlich kleiner.

Endpunkt	Großes Feld	Kleiner mit
Transkript einer Aufnahme	`segments`	`fields=recordingId,speakers`
Einzelne Zusammenfassung	`sectionItems`	`fields=recordingSummaryId,languageCode,summary`
Terminliste	`attendees`, `description`	`fields=appointmentId,subject,startTime`

Diese Anfrage holt nur die Sprecher eines Transkripts, etwa um sie deinen Nutzern zuzuordnen, bevor du den Text lädst:

cURL
JavaScript
Python

curl "https://api.sally.io/v1.0/directories/$DIRECTORY_ID/recordings/$RECORDING_ID/transcription?fields=recordingId,speakers" \
  -H "Authorization: Bearer $SALLY_TOKEN"

const url = new URL(
  `https://api.sally.io/v1.0/directories/${directoryId}/recordings/${recordingId}/transcription`,
);
url.searchParams.set('fields', 'recordingId,speakers');

const response = await fetch(url, {
  headers: {Authorization: `Bearer ${process.env.SALLY_TOKEN}`},
});
const {speakers} = await response.json();

import os
import requests

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

200 OK
{
  "recordingId": "53e2e041-4b34-41c7-a285-634d80b3675d",
  "speakers": [
    {
      "speakerId": "b16c2c6f-d9f5-4709-a27e-41a319410893",
      "speakerNumber": 1,
      "name": "Anna Berger",
      "emailAddress": "anna.berger@example.com"
    }
  ]
}

Die Endpunkte aus der Tabelle in der Referenz, wo du jede Auswahl mit deinem eigenen Token ausprobieren kannst:

1. Felder auswählen​

2. Die Regeln​

3. Unbekannte Namen werden abgelehnt​

4. Wo es sich lohnt​

1. Felder auswählen

2. Die Regeln

3. Unbekannte Namen werden abgelehnt

4. Wo es sich lohnt