Summaries

A summary belongs to one recording and exists once per language. Use these endpoints to search summaries, to fetch a single summary by its id and to download it as a finished file.

Every endpoint below shows its parameters and response fields in the middle. On the right you find request samples in cURL, JavaScript and Python, an example response and Try it, which sends the request for real with your own token.

Searches recording summaries (parameters in the body)

POST/v1.0/directories/{directoryId}/summaries/searchTry it →

Searches recording summaries and returns a truncated snippet of the summary text per hit.

Field overview from the specification

Body fields:

search (string, optional, min. 3 characters): case-insensitive substring, matched anywhere over the summary text, the generated section items (title/content/subject/description) AND the cells of a structured table section; a recording is a hit if ANY of these matches.
page (number, optional, default 1): 1-based page number.
pageSize (number, optional, default 25): page size, max. 100.

Path parameters

directoryIdstringrequired
Id of the directory (the Sally company account) the resource belongs to. The directories a token can address are listed by GET /v1.0/me/directories/memberships.

Query parameters

fieldsstringoptional
Comma-separated list of the fields to return. Leave it out and you get every field — including fields added in the future, which is your call to make: name your fields if you want to be shielded from that.
Only first-level fields can be named. A nested list such as attendees, tags or sectionItems is returned whole or not at all; attendees.name is not supported.
On a paged response the selection applies to the entries in items; page, pageSize, total and hasMore are always returned. An unknown name is rejected with 400 rather than ignored.
Selectable here: appointmentId, createdOn, languageCode, recordingId, recordingSummaryId, snippet.
Example: appointmentId,createdOn

Request body application/json

searchstringoptionalnullable
Case-insensitive substring match over the summary text and the generated section items (title/content/subject/description). Min. 3 characters.
pagenumberoptional
Page (1-based, default 1).
pageSizenumberoptional
Page size (default 25, max 100).

Response: each entry in items

recordingSummaryIdstringrequired
Id of the recording summary.
recordingIdstringrequired
Associated recording id.
appointmentIdstringrequirednullable
Associated appointment id (if present).
languageCodestringrequirednullable
Language code of the summary (IETF language tag, e.g. de-DE, en-US).
snippetstringrequired
Truncated excerpt of the summary text (max. 300 characters).
createdOnstringrequired
Creation timestamp (ISO-8601).

Every page also carries page, pageSize, total, hasMore.

Status codes

200Success
400
Invalid request (validation error).
401
Missing or invalid bearer token.
403
Forbidden (insufficient permissions).
404
Resource not found or not accessible.
429
Rate limit exceeded (per token/IP). Transcription uploads may also return code FUP_LIMIT_EXCEEDED or TOO_MANY_CONCURRENT_TRANSCRIPTIONS.
500
Internal server error.

Try it

Send this request for real, with your own token and your own data.

Request

cURL
JavaScript
Python

curl -X POST "https://api.sally.io/v1.0/directories/$DIRECTORY_ID/summaries/search" \
  -H "Authorization: Bearer $SALLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "search": "pricing",
  "page": 1,
  "pageSize": 25
}'

const response = await fetch(`https://api.sally.io/v1.0/directories/${directoryId}/summaries/search`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SALLY_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "search": "pricing",
    "page": 1,
    "pageSize": 25
  }),
});
const data = await response.json();

import os
import requests

response = requests.post(
    f"https://api.sally.io/v1.0/directories/{directory_id}/summaries/search",
    headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
    json={
        "search": "pricing",
        "page": 1,
        "pageSize": 25,
    },
)
data = response.json()

Response example 200 OK

{
  "page": 1,
  "pageSize": 25,
  "total": 137,
  "hasMore": true,
  "items": [
    {
      "recordingSummaryId": "731180f9-257a-46cf-a7e3-8ca508fb9c35",
      "recordingId": "53e2e041-4b34-41c7-a285-634d80b3675d",
      "appointmentId": "d4398f97-cd92-4d21-a6ec-4aab0a85441b",
      "languageCode": "de-DE",
      "snippet": "string",
      "createdOn": "2026-09-24T09:30:00Z"
    }
  ]
}

Returns a single recording summary by id

GET/v1.0/directories/{directoryId}/summaries/{recordingSummaryId}Try it →

Returns the full recording summary for the given recordingSummaryId. 404 if the summary does not exist or the caller cannot access the underlying recording. Obtain valid ids from the summary search (POST .../summaries/search) or from GET .../recordings/{recordingId}/summaries.

Field overview from the specification

Path parameters:

directoryId (string): id of the directory (organization) the summary belongs to.
recordingSummaryId (string): id of the recording summary to return.

Response fields:

recordingSummaryId (string): id of this summary. A recording can have several summaries — one per language.
recordingId (string): id of the recording this summary was generated from.
appointmentId (string | null): id of the caller’s own appointment linked to the recording; null if the recording is not linked to an appointment.
languageCode (string | null): language of the summary text as an IETF language tag (e.g. de-DE, en-US); null if unknown.
summary (string | null): the summary text (Markdown); null if no summary text was generated.
createdOn (string): creation timestamp of the summary (UTC ISO-8601).
sectionItems (array): the structured, per-section results of the meeting template that produced this summary (always included on this endpoint). Each item has:
- sectionItemId (string): id of the section item.
- meetingTemplateSectionId (string | null): id of the meeting-template section this item was generated from (resolve via GET .../meetingtemplates/{meetingTemplateId}); null for derived items without a template section (e.g. task items).
- title (string): title of the section item.
- sectionType (string enum): the section type (summary, tasks, topics, decisions, customList, freeText, table, appointment or email).
- outputFormat (string enum): the format of content (html or markdown).
- sortOrder (number): order of the item within the summary.
- content (string | null): the free-text/Markdown content of the item. For table, appointment and email it carries a readable Markdown rendering of the dedicated fields below, so a client that only reads content still sees the section; outputFormat is then markdown.
- tableVariant (string enum | null): only for table. structured means the columns were fixed in the template and the result is in tableData; free means Sally chose them and the result is a Markdown table in content.
- tableData (object | null): columns and rows of a structured table section.
- followUpMeetingStartTime / followUpMeetingEndTime (string | null): the agreed wall-clock time of an appointment section, without a time zone.
- followUpMeetingParticipants (array | null): participants of an appointment section.
- emailRecipients (array | null): recipients of an email section, to and cc in one list, told apart by kind.
- subject (string | null): task subject (for task-like section items).
- description (string | null): task description (for task-like section items).
- responsibleUserName (string | null): name of the responsible person (task items).
- responsibleUserEmail (string | null): email of the responsible person (task items).
- dueDate (string | null): due date of the task item (ISO-8601).

Path parameters

directoryIdstringrequired
Id of the directory (the Sally company account) the resource belongs to. The directories a token can address are listed by GET /v1.0/me/directories/memberships.
recordingSummaryIdstringrequired
Id of the recording summary.

Query parameters

fieldsstringoptional
Comma-separated list of the fields to return. Leave it out and you get every field — including fields added in the future, which is your call to make: name your fields if you want to be shielded from that.
Only first-level fields can be named. A nested list such as attendees, tags or sectionItems is returned whole or not at all; attendees.name is not supported.
On a paged response the selection applies to the entries in items; page, pageSize, total and hasMore are always returned. An unknown name is rejected with 400 rather than ignored.
Selectable here: appointmentId, createdOn, isSummarizationCompleted, isSummarizationSucceeded, languageCode, recordingId, recordingSummaryId, sectionItems, summarizationCompletionReason, summary.
Example: appointmentId,createdOn

Response

recordingSummaryIdstringrequired
Id of the recording summary.
recordingIdstringrequired
Associated recording id.
appointmentIdstringrequirednullable
Associated appointment id (if present).
languageCodestringrequirednullable
Language code of the summary (IETF language tag, e.g. de-DE, en-US).
summarystringrequirednullable
Summary text.
isSummarizationCompletedbooleanrequired
True once the summarization run has finished, whether or not it produced anything.
isSummarizationSucceededbooleanrequired
True when there is something to read: summary text or at least one section item. A run over a recording without a transcript finishes too, and then this stays false.
summarizationCompletionReasonstringrequired
Why the summarization run ended. noTranscript means there was nothing to summarize, which is an expected outcome and not a failure. unknown while it has not finished. The underlying error text is deliberately not exposed.
Allowed values: succeedednoTranscriptemptyResulterrorunknown
createdOnstringrequired
Creation timestamp (ISO-8601).
sectionItemsobject[]requirednullable
The generated section items of the summary (the structured, per-section results of the meeting template). Null when not loaded (the recordings list endpoint only fills this with ?includeDetails=true); the single-summary endpoint always includes it.
18 child fields
- sectionItemIdstringrequired
  Id of the section item.
- meetingTemplateSectionIdstringrequirednullable
  Id of the meeting template section this item was generated from. Resolve it via GET /v1.0/directories/{directoryId}/meetingtemplates/{meetingTemplateId} (matches a section’s meetingTemplateSectionId). Null for derived items without a template section (e.g. task items).
- titlestringrequired
  Title of the template section item.
- sectionTypestringrequired
  Section type of the item.
  Allowed values: summarytaskstopicsdecisionscustomListfreeTexttableappointmentemailunknown
- outputFormatstringrequired
  Output format of the item content.
  Allowed values: htmlmarkdownunknown
- sortOrdernumberrequired
  Order within the summary.
- contentstringrequirednullable
  Free-text/Markdown content of the item. For the section types that keep their result in dedicated fields (table, appointment, email), this carries a readable Markdown rendering of those fields, so a client that only reads this one field still sees the section. The dedicated fields are returned unchanged alongside it.
- subjectstringrequirednullable
  Task subject (for task-like section items).
- descriptionstringrequirednullable
  Task description.
- responsibleUserNamestringrequirednullable
  Responsible person (name).
- responsibleUserEmailstringrequirednullable
  Responsible person (email).
- dueDatestringrequirednullable
  Due date (ISO-8601).
- tableVariantstringrequirednullable
  Only for sectionType: table. structured means the template fixed the columns and the result is in tableData. free means Sally chose the columns herself and the result is a Markdown table in content. Null for every other section type.
  Allowed values: freestructuredunknown
- tableDataanyrequirednullable
  The table result, set only for sectionType: table with tableVariant: structured. For tableVariant: free this is null and the table is a Markdown table in content.
- followUpMeetingStartTimestringrequirednullable
  Start of the proposed follow-up meeting, as a LOCAL date and time WITHOUT a time zone (YYYY-MM-DDTHH:mm:ss, e.g. 2026-10-16T09:00:00). Deliberately not a UTC instant: what the meeting agreed on is a wall-clock hour (Thursday at nine), and attaching a zone here would move that hour for every reader in a different one. Apply the time zone of the people involved. Only set for sectionType: appointment.
- followUpMeetingEndTimestringrequirednullable
  End of the proposed follow-up meeting, same local-time format as followUpMeetingStartTime. Null when the meeting named a start but no end.
- followUpMeetingParticipantsobject[]requirednullable
  The people the meeting named for the follow-up. Only set for sectionType: appointment.
  4 child fields
  - userIdstringrequirednullable
    Id of the matched user account, or null when no account was found for this person. Resolve it via GET /v1.0/directories/{directoryId}/memberships/users/{userId}.
  - namestringrequired
    Name of the person as recognized in the meeting.
  - emailstringrequirednullable
    Email address as recognized in the meeting, lower-cased. Null when the meeting named the person without an address.
  - isExternalbooleanrequirednullable
    True when the person was recognized as not belonging to your own organization. Null when the meeting gave no indication either way.
- emailRecipientsobject[]requirednullable
  Recipients of the proposed email, direct and on copy (see kind). Only set for sectionType: email; its subject is in subject and its body in description.
  4 child fields
  - userIdstringrequirednullable
    Id of the matched user account, or null when no account was found for this person. Resolve it via GET /v1.0/directories/{directoryId}/memberships/users/{userId}.
  - namestringrequired
    Name of the person as recognized in the meeting.
  - emailstringrequirednullable
    Email address as recognized in the meeting, lower-cased. Null when the meeting named the person without an address.
  - kindstringrequired
    Whether the person is a direct recipient (to) or on copy (cc).
    Allowed values: tocc

Status codes

200Success
400
Invalid request (validation error).
401
Missing or invalid bearer token.
404
Resource not found or not accessible.
429
Rate limit exceeded (per token/IP). Transcription uploads may also return code FUP_LIMIT_EXCEEDED or TOO_MANY_CONCURRENT_TRANSCRIPTIONS.
500
Internal server error.

Try it

Send this request for real, with your own token and your own data.

Request

cURL
JavaScript
Python

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

const response = await fetch(`https://api.sally.io/v1.0/directories/${directoryId}/summaries/${recordingSummaryId}`, {
  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}/summaries/{recording_summary_id}",
    headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
)
data = response.json()

Response example 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": [
        {
          "userId": "11f967df-7dd1-4719-a9aa-46530940c443",
          "name": "Example",
          "email": "anna.berger@example.com",
          "isExternal": true
        }
      ],
      "emailRecipients": [
        {
          "userId": "11f967df-7dd1-4719-a9aa-46530940c443",
          "name": "Example",
          "email": "anna.berger@example.com",
          "kind": "to"
        }
      ]
    }
  ]
}

Returns a recording summary as a finished document file

GET/v1.0/directories/{directoryId}/summaries/{recordingSummaryId}/documentTry it →

Returns the same file the Sally web app downloads for this summary: branding, logos, header and footer, tables and the section order of the meeting template. The file is built on request and returned directly in the response; there is no job to poll.

Always the complete summary in the language version identified by recordingSummaryId (a recording has one summary per language, see GET .../recordings/{recordingId}/summaries). Custom insights and single sections are not part of this document.

Field overview from the specification

Path parameters:

directoryId (string): id of the directory the summary belongs to.
recordingSummaryId (string): id of the recording summary.

Query parameters:

format (string enum, required): one of pdf, docx, odt, txt, md.
languageCode (string enum, optional): one of de-DE, en-US, es-ES, fr-FR, it-IT, nl-NL, pl-PL; defaults to the language of the token owner.

This endpoint does not support ?fields=.

Path parameters

directoryIdstringrequired
Id of the directory (the Sally company account) the resource belongs to. The directories a token can address are listed by GET /v1.0/me/directories/memberships.
recordingSummaryIdstringrequired
Id of the recording summary.

Query parameters

formatstringrequired
File format of the document.
Allowed values: pdfdocxodttxtmd
languageCodestringoptional
IETF language tag for the labels and the date format inside the document, e.g. de-DE. Defaults to the language of the token owner, exactly as in the Sally web app. It does NOT change the language of the content, and the font is always chosen by the language of the recording, so Chinese characters stay readable with en-US labels.
Allowed values: de-DEen-USes-ESfr-FRit-ITnl-NLpl-PL

Status codes

200The file itself. `Content-Disposition` carries the file name that the Sally web app uses for the same download (ASCII in `filename`, UTF-8 in `filename*`).
400
Unknown or missing format, or unknown languageCode. The body lists the allowed values (code: UNKNOWN_DOCUMENT_FORMAT or UNKNOWN_LANGUAGE_CODE).
401
Missing or invalid bearer token.
403
The directory has disabled this download for its members (code: SUMMARY_DOWNLOAD_PREVENTED).
404
The source does not exist, belongs to another directory, or the caller cannot access the underlying recording.
409
The summary has no content that could be put into a document (it was generated before meeting templates existed, or its template has no sections) (code: SUMMARY_HAS_NO_CONTENT).
429
Rate limit exceeded (per token/IP). Transcription uploads may also return code FUP_LIMIT_EXCEEDED or TOO_MANY_CONCURRENT_TRANSCRIPTIONS.
500
Internal server error.

Try it

Send this request for real, with your own token and your own data.

Request

cURL
JavaScript
Python

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

const response = await fetch(`https://api.sally.io/v1.0/directories/${directoryId}/summaries/${recordingSummaryId}/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}/summaries/{recording_summary_id}/document?format=pdf",
    headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
)
content = response.content

Response example 200 OK

"string"

Searches recording summaries (parameters in the body)​

Path parameters

Query parameters

Request body application/json

Response: each entry in items

Status codes

Returns a single recording summary by id​

Path parameters

Query parameters

Response

Status codes

Returns a recording summary as a finished document file​

Path parameters

Query parameters

Status codes

Searches recording summaries (parameters in the body)

Returns a single recording summary by id

Returns a recording summary as a finished document file