Folders

A folder organizes recordings in a tree and controls who can see them. These endpoints read and update folders, manage their shares and move recordings in and out.

Every endpoint below shows its parameters and response fields in the middle and a request sample with an example response on the right.

Base URL https://api.sally.ioVersion v1.0 current, not frozen yetHow versioning works

Lists the recording folders the caller can access (paginated, optionally filtered)

GET/v1.0/directories/{directoryId}/folders

Merges personal, shared and team folders into one list. Pagination via ?page + ?pageSize (max. 100, applied in-memory). An optional ?search substring matches the folder name (case-insensitive). Pass ?parentRecordingFolderId to list only the direct children of a folder; omit it to list all folders.

Field overview from the specification

Response fields:

• page / pageSize / total / hasMore: pagination envelope (current page, page size, total count, whether more pages follow).
• items (array): the folders on this page. Each item has:
  • folderId (string): id of the folder.
  • name (string): folder display name.
  • description (string | null): folder description; null if unset.
  • ownerUserId (string): id of the user who owns the folder.
  • parentFolderId (string | null): id of the parent folder; null if this is a top-level folder.
  • isOwner (boolean): true if the caller is the owner of the folder.
  • isFavorite (boolean): true if the caller marked the folder as favorite.
  • accessLevel (string, one of none/read/readWrite): the caller's effective access level on the folder.
  • recordingsCount (number): number of recordings in the folder.
  • createdOn (string): creation timestamp (ISO 8601).
  • modifiedOn (string): last modification timestamp (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.

Query parameters

• pagenumberoptional

  Page number, 1-based. Defaults to 1.

• pageSizenumberoptional

  Items per page. Defaults to 25, capped at 100.

• searchstringoptional

  Case-insensitive substring match on the folder name. The term may appear at the start, middle, or end.

• parentRecordingFolderIdstringoptional

  Id of the parent recording folder.

• 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: accessLevel, createdOn, description, folderId, isFavorite, isOwner, modifiedOn, name, ownerUserId, parentFolderId, recordingsCount.

  Example: accessLevel,createdOn

Response: each entry in items

• folderIdstringrequired

  Id of the folder.

• namestringrequired

  Folder display name.

• descriptionstringrequirednullable

  Folder description; null if unset.

• ownerUserIdstringrequired

  Id of the user who owns the folder.

• parentFolderIdstringrequirednullable

  Id of the parent folder; null if this is a top-level folder.

• isOwnerbooleanrequired

  True if the caller is the owner of the folder.

• isFavoritebooleanrequired

  True if the caller marked the folder as favorite.

• accessLevelstringrequired

  The caller's effective access level on the folder.

  Allowed values: nonereadreadWrite
• recordingsCountnumberrequired

  Number of recordings in the folder.

• createdOnstringrequired

  Creation timestamp (ISO 8601).

• modifiedOnstringrequired

  Last modification 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.

• 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.

Request

cURL

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

JavaScript

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

Python

import os
import requests

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

Response example 200 OK

{
  "page": 1,
  "pageSize": 25,
  "total": 137,
  "hasMore": true,
  "items": [
    {
      "folderId": "f0186448-90aa-4df8-a13d-17a832c35c28",
      "name": "Sales calls",
      "description": "string",
      "ownerUserId": "eece96ba-87a6-4f16-a07d-a7720d671312",
      "parentFolderId": "bf7cd0f0-3c69-4690-a956-9c30b123ab30",
      "isOwner": true,
      "isFavorite": true,
      "accessLevel": "none",
      "recordingsCount": 3,
      "createdOn": "2026-09-24T09:30:00Z",
      "modifiedOn": "2026-09-24T09:30:00Z"
    }
  ]
}

Searches recording folders (parameters in the body)

POST/v1.0/directories/{directoryId}/folders/search

Searches recording folders. Merges personal, shared and team folders into one list and paginates in-memory.

Field overview from the specification

Body fields:

• search (string, optional): case-insensitive substring on the folder name.
• parentRecordingFolderId (string, optional): list only the direct children of that folder; omit for all folders.
• 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: accessLevel, createdOn, description, folderId, isFavorite, isOwner, modifiedOn, name, ownerUserId, parentFolderId, recordingsCount.

  Example: accessLevel,createdOn

Request body application/json

• searchstringoptionalnullable

  Case-insensitive substring match on the folder name. The term may appear at the start, middle, or end.

• parentRecordingFolderIdstringoptionalnullable

  List only the direct children of this folder; omit for all folders.

• pagenumberoptional

  Page (1-based, default 1).

• pageSizenumberoptional

  Page size (default 25, max 100).

Response: each entry in items

• folderIdstringrequired

  Id of the folder.

• namestringrequired

  Folder display name.

• descriptionstringrequirednullable

  Folder description; null if unset.

• ownerUserIdstringrequired

  Id of the user who owns the folder.

• parentFolderIdstringrequirednullable

  Id of the parent folder; null if this is a top-level folder.

• isOwnerbooleanrequired

  True if the caller is the owner of the folder.

• isFavoritebooleanrequired

  True if the caller marked the folder as favorite.

• accessLevelstringrequired

  The caller's effective access level on the folder.

  Allowed values: nonereadreadWrite
• recordingsCountnumberrequired

  Number of recordings in the folder.

• createdOnstringrequired

  Creation timestamp (ISO 8601).

• modifiedOnstringrequired

  Last modification 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.

Request

cURL

curl -X POST "https://api.sally.io/v1.0/directories/$DIRECTORY_ID/folders/search" \
  -H "Authorization: Bearer $SALLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "search": "pricing",
  "parentRecordingFolderId": "8cd0dc2d-d9b6-453b-a69b-2e49f3a8f119",
  "page": 1,
  "pageSize": 25
}'

JavaScript

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

Python

import os
import requests

response = requests.post(
    f"https://api.sally.io/v1.0/directories/{directory_id}/folders/search",
    headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
    json={
        "search": "pricing",
        "parentRecordingFolderId": "8cd0dc2d-d9b6-453b-a69b-2e49f3a8f119",
        "page": 1,
        "pageSize": 25,
    },
)
data = response.json()

Response example 200 OK

{
  "page": 1,
  "pageSize": 25,
  "total": 137,
  "hasMore": true,
  "items": [
    {
      "folderId": "f0186448-90aa-4df8-a13d-17a832c35c28",
      "name": "Sales calls",
      "description": "string",
      "ownerUserId": "eece96ba-87a6-4f16-a07d-a7720d671312",
      "parentFolderId": "bf7cd0f0-3c69-4690-a956-9c30b123ab30",
      "isOwner": true,
      "isFavorite": true,
      "accessLevel": "none",
      "recordingsCount": 3,
      "createdOn": "2026-09-24T09:30:00Z",
      "modifiedOn": "2026-09-24T09:30:00Z"
    }
  ]
}

Returns a single recording folder

GET/v1.0/directories/{directoryId}/folders/{folderId}

The caller must be a member of the directory and have at least read access to the folder — otherwise 404/403. accessLevel reflects the effective access of the caller.

Field overview from the specification

Response fields:

• folderId (string): id of the folder.
• name (string): folder display name.
• description (string | null): folder description; null if unset.
• ownerUserId (string): id of the user who owns the folder.
• parentFolderId (string | null): id of the parent folder; null if this is a top-level folder.
• isOwner (boolean): true if the caller is the owner of the folder.
• isFavorite (boolean): true if the caller marked the folder as favorite.
• accessLevel (string, one of none/read/readWrite): the caller's effective access level on the folder.
• recordingsCount (number): number of recordings in the folder.
• createdOn (string): creation timestamp (ISO 8601).
• modifiedOn (string): last modification timestamp (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.

• folderIdstringrequired

  Id of the folder.

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: accessLevel, createdOn, description, folderId, isFavorite, isOwner, modifiedOn, name, ownerUserId, parentFolderId, recordingsCount.

  Example: accessLevel,createdOn

Response

• folderIdstringrequired

  Id of the folder.

• namestringrequired

  Folder display name.

• descriptionstringrequirednullable

  Folder description; null if unset.

• ownerUserIdstringrequired

  Id of the user who owns the folder.

• parentFolderIdstringrequirednullable

  Id of the parent folder; null if this is a top-level folder.

• isOwnerbooleanrequired

  True if the caller is the owner of the folder.

• isFavoritebooleanrequired

  True if the caller marked the folder as favorite.

• accessLevelstringrequired

  The caller's effective access level on the folder.

  Allowed values: nonereadreadWrite
• recordingsCountnumberrequired

  Number of recordings in the folder.

• createdOnstringrequired

  Creation timestamp (ISO 8601).

• modifiedOnstringrequired

  Last modification timestamp (ISO 8601).

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.

Request

cURL

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

JavaScript

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

Python

import os
import requests

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

Response example 200 OK

{
  "folderId": "f0186448-90aa-4df8-a13d-17a832c35c28",
  "name": "Sales calls",
  "description": "string",
  "ownerUserId": "eece96ba-87a6-4f16-a07d-a7720d671312",
  "parentFolderId": "bf7cd0f0-3c69-4690-a956-9c30b123ab30",
  "isOwner": true,
  "isFavorite": true,
  "accessLevel": "none",
  "recordingsCount": 3,
  "createdOn": "2026-09-24T09:30:00Z",
  "modifiedOn": "2026-09-24T09:30:00Z"
}

Updates a recording folder (name, description, parent)

PATCH/v1.0/directories/{directoryId}/folders/{folderId}

Updates the folder metadata. Only the provided fields are changed (partial); the shares are left untouched (use PUT .../folders/{folderId}/shares for those). Requires read-write access to the folder. Returns the updated folder.

Field overview from the specification

Body fields:

• name (string, optional): new folder name; omit to leave unchanged.
• description (string, optional): new description; null clears it, omit to leave unchanged.
• parentFolderId (string, optional): id of the new parent folder to move this folder under; null makes it a top-level folder, omit to leave unchanged.

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.

• folderIdstringrequired

  Id of the folder.

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: accessLevel, createdOn, description, folderId, isFavorite, isOwner, modifiedOn, name, ownerUserId, parentFolderId, recordingsCount.

  Example: accessLevel,createdOn

Request body application/json

• namestringoptional

  New folder name (omit to leave unchanged).

• descriptionstringoptionalnullable

  New folder description; null to clear, omit to leave unchanged.

• parentFolderIdstringoptionalnullable

  Id of the new parent folder to move this folder under; null to make it a top-level folder, omit to leave unchanged.

Response

• folderIdstringrequired

  Id of the folder.

• namestringrequired

  Folder display name.

• descriptionstringrequirednullable

  Folder description; null if unset.

• ownerUserIdstringrequired

  Id of the user who owns the folder.

• parentFolderIdstringrequirednullable

  Id of the parent folder; null if this is a top-level folder.

• isOwnerbooleanrequired

  True if the caller is the owner of the folder.

• isFavoritebooleanrequired

  True if the caller marked the folder as favorite.

• accessLevelstringrequired

  The caller's effective access level on the folder.

  Allowed values: nonereadreadWrite
• recordingsCountnumberrequired

  Number of recordings in the folder.

• createdOnstringrequired

  Creation timestamp (ISO 8601).

• modifiedOnstringrequired

  Last modification timestamp (ISO 8601).

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.

Request

cURL

curl -X PATCH "https://api.sally.io/v1.0/directories/$DIRECTORY_ID/folders/$FOLDER_ID" \
  -H "Authorization: Bearer $SALLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Example",
  "description": "string",
  "parentFolderId": "bf7cd0f0-3c69-4690-a956-9c30b123ab30"
}'

JavaScript

const response = await fetch(`https://api.sally.io/v1.0/directories/${directoryId}/folders/${folderId}`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.SALLY_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Example",
    "description": "string",
    "parentFolderId": "bf7cd0f0-3c69-4690-a956-9c30b123ab30"
  }),
});
const data = await response.json();

Python

import os
import requests

response = requests.patch(
    f"https://api.sally.io/v1.0/directories/{directory_id}/folders/{folder_id}",
    headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
    json={
        "name": "Example",
        "description": "string",
        "parentFolderId": "bf7cd0f0-3c69-4690-a956-9c30b123ab30",
    },
)
data = response.json()

Response example 200 OK

{
  "folderId": "f0186448-90aa-4df8-a13d-17a832c35c28",
  "name": "Sales calls",
  "description": "string",
  "ownerUserId": "eece96ba-87a6-4f16-a07d-a7720d671312",
  "parentFolderId": "bf7cd0f0-3c69-4690-a956-9c30b123ab30",
  "isOwner": true,
  "isFavorite": true,
  "accessLevel": "none",
  "recordingsCount": 3,
  "createdOn": "2026-09-24T09:30:00Z",
  "modifiedOn": "2026-09-24T09:30:00Z"
}

Returns the shares of a recording folder

GET/v1.0/directories/{directoryId}/folders/{folderId}/shares

Direct user shares, team shares and inherited shares (from parent folders). Each share carries only ids + access level; resolve user/team details via the membership/team endpoints.

Field overview from the specification

Response fields:

• userShares (array): direct user shares of the folder. Each item has:
  • userId (string): id of the user this folder is shared with.
  • accessLevel (string, one of none/read/readWrite): access level granted to the user.
• teamShares (array): team shares of the folder. Each item has:
  • teamId (string): id of the team this folder is shared with.
  • accessLevel (string, one of none/read/readWrite): access level granted to the team.
• inheritedShares (array): shares inherited from parent folders (read-only). Each item has:
  • userId (string): id of the user who inherits access.
  • accessLevel (string, one of none/read/readWrite): inherited access level.
  • inheritedFromFolderId (string): id of the parent folder the access is inherited from.

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.

• folderIdstringrequired

  Id of the folder.

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: inheritedShares, teamShares, userShares.

  Example: inheritedShares,teamShares

Response

• userSharesobject[]required

  Direct user shares of the folder.

  2 child fields

  • userIdstringrequired

    Id of the user this folder is shared with.

  • accessLevelstringrequired

    Access level granted to the user.

    Allowed values: nonereadreadWrite
• teamSharesobject[]required

  Team shares of the folder.

  2 child fields

  • teamIdstringrequired

    Id of the team this folder is shared with.

  • accessLevelstringrequired

    Access level granted to the team.

    Allowed values: nonereadreadWrite
• inheritedSharesobject[]required

  Shares inherited from parent folders (read-only).

  3 child fields

  • userIdstringrequired

    Id of the user who inherits access.

  • accessLevelstringrequired

    Inherited access level.

    Allowed values: nonereadreadWrite
  • inheritedFromFolderIdstringrequired

    Id of the parent folder the access is inherited from.

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.

Request

cURL

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

JavaScript

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

Python

import os
import requests

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

Response example 200 OK

{
  "userShares": [
    {
      "userId": "11f967df-7dd1-4719-a9aa-46530940c443",
      "accessLevel": "none"
    }
  ],
  "teamShares": [
    {
      "teamId": "3c35d421-a578-4ce7-aebb-c5add21907bd",
      "accessLevel": "none"
    }
  ],
  "inheritedShares": [
    {
      "userId": "11f967df-7dd1-4719-a9aa-46530940c443",
      "accessLevel": "none",
      "inheritedFromFolderId": "a1ae243c-6bc2-4da4-a5d7-d70c50ba1acc"
    }
  ]
}

Sets the shares of a recording folder (replace-set)

PUT/v1.0/directories/{directoryId}/folders/{folderId}/shares

Replaces the direct user shares and team shares of the folder with the provided sets (inherited shares are read-only and cannot be set). Only the folder owner may change shares. Returns the resulting shares.

Field overview from the specification

Body fields:

• userShares (array, required): direct user shares to apply, each { userId (string), accessLevel (none/read/readWrite) }. The resulting set replaces the current one.
• teamShares (array, required): team shares to apply, each { teamId (string), accessLevel (none/read/readWrite) }. The resulting set replaces the current one.

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.

• folderIdstringrequired

  Id of the folder.

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: inheritedShares, teamShares, userShares.

  Example: inheritedShares,teamShares

Request body application/json

• userSharesobject[]required

  Direct user shares to apply. The resulting set replaces the current one.

  2 child fields

  • userIdstringrequired

    Id of the user this folder is shared with.

  • accessLevelstringrequired

    Access level granted to the user.

    Allowed values: nonereadreadWrite
• teamSharesobject[]required

  Team shares to apply. The resulting set replaces the current one.

  2 child fields

  • teamIdstringrequired

    Id of the team this folder is shared with.

  • accessLevelstringrequired

    Access level granted to the team.

    Allowed values: nonereadreadWrite

Response

• userSharesobject[]required

  Direct user shares of the folder.

  2 child fields

  • userIdstringrequired

    Id of the user this folder is shared with.

  • accessLevelstringrequired

    Access level granted to the user.

    Allowed values: nonereadreadWrite
• teamSharesobject[]required

  Team shares of the folder.

  2 child fields

  • teamIdstringrequired

    Id of the team this folder is shared with.

  • accessLevelstringrequired

    Access level granted to the team.

    Allowed values: nonereadreadWrite
• inheritedSharesobject[]required

  Shares inherited from parent folders (read-only).

  3 child fields

  • userIdstringrequired

    Id of the user who inherits access.

  • accessLevelstringrequired

    Inherited access level.

    Allowed values: nonereadreadWrite
  • inheritedFromFolderIdstringrequired

    Id of the parent folder the access is inherited from.

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.

Request

cURL

curl -X PUT "https://api.sally.io/v1.0/directories/$DIRECTORY_ID/folders/$FOLDER_ID/shares" \
  -H "Authorization: Bearer $SALLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "userShares": [
    {
      "userId": "11f967df-7dd1-4719-a9aa-46530940c443",
      "accessLevel": "none"
    }
  ],
  "teamShares": [
    {
      "teamId": "3c35d421-a578-4ce7-aebb-c5add21907bd",
      "accessLevel": "none"
    }
  ]
}'

JavaScript

const response = await fetch(`https://api.sally.io/v1.0/directories/${directoryId}/folders/${folderId}/shares`, {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.SALLY_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "userShares": [
      {
        "userId": "11f967df-7dd1-4719-a9aa-46530940c443",
        "accessLevel": "none"
      }
    ],
    "teamShares": [
      {
        "teamId": "3c35d421-a578-4ce7-aebb-c5add21907bd",
        "accessLevel": "none"
      }
    ]
  }),
});
const data = await response.json();

Python

import os
import requests

response = requests.put(
    f"https://api.sally.io/v1.0/directories/{directory_id}/folders/{folder_id}/shares",
    headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
    json={
        "userShares": [
            {
                "userId": "11f967df-7dd1-4719-a9aa-46530940c443",
                "accessLevel": "none",
            },
        ],
        "teamShares": [
            {
                "teamId": "3c35d421-a578-4ce7-aebb-c5add21907bd",
                "accessLevel": "none",
            },
        ],
    },
)
data = response.json()

Response example 200 OK

{
  "userShares": [
    {
      "userId": "11f967df-7dd1-4719-a9aa-46530940c443",
      "accessLevel": "none"
    }
  ],
  "teamShares": [
    {
      "teamId": "3c35d421-a578-4ce7-aebb-c5add21907bd",
      "accessLevel": "none"
    }
  ],
  "inheritedShares": [
    {
      "userId": "11f967df-7dd1-4719-a9aa-46530940c443",
      "accessLevel": "none",
      "inheritedFromFolderId": "a1ae243c-6bc2-4da4-a5d7-d70c50ba1acc"
    }
  ]
}

Lists the recordings in a folder (paginated)

GET/v1.0/directories/{directoryId}/folders/{folderId}/recordings

Pass ?includeSubfolders=true to also include the recordings of all accessible subfolders (recursive, deduplicated). Sorted by creation date descending. Pagination via ?page + ?pageSize (max. 100, applied in-memory). Each item references the recording by recordingId; fetch full details via GET .../recordings/{recordingId}.

Field overview from the specification

Response fields:

• page / pageSize / total / hasMore: pagination envelope (current page, page size, total count, whether more pages follow).
• items (array): the recordings on this page. Each item has:
  • recordingId (string): id of the recording.
  • durationInSeconds (number | null): duration in seconds; null if unknown.
  • isManualUpload (boolean): true if manually uploaded (no meeting bot).
  • appointmentId (string | null): id of the caller's own appointment linked to the recording; null if none.
  • createdOn (string): creation timestamp (ISO 8601, UTC).

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.

• folderIdstringrequired

  Id of the folder.

Query parameters

• includeSubfoldersbooleanoptional

  When true, recordings of all nested subfolders are included as well. When omitted or false, only the recordings placed directly in this folder are returned.

• pagenumberoptional

  Page number, 1-based. Defaults to 1.

• pageSizenumberoptional

  Items per page. Defaults to 25, capped at 100.

• 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, durationInSeconds, isManualUpload, recordingId.

  Example: appointmentId,createdOn

Response: each entry in items

• recordingIdstringrequired

  Id of the recording.

• durationInSecondsnumberrequirednullable

  Duration in seconds; null if unknown.

• isManualUploadbooleanrequired

  True if manually uploaded (no meeting bot).

• appointmentIdstringrequirednullable

  Id of the caller's own appointment linked to the recording; null if none.

• createdOnstringrequired

  Creation timestamp (ISO 8601, UTC).

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

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.

Request

cURL

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

JavaScript

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

Python

import os
import requests

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

Response example 200 OK

{
  "page": 1,
  "pageSize": 25,
  "total": 137,
  "hasMore": true,
  "items": [
    {
      "recordingId": "53e2e041-4b34-41c7-a285-634d80b3675d",
      "durationInSeconds": 1843,
      "isManualUpload": true,
      "appointmentId": "d4398f97-cd92-4d21-a6ec-4aab0a85441b",
      "createdOn": "2026-09-24T09:30:00Z"
    }
  ]
}

Adds a recording to a folder

PUT/v1.0/directories/{directoryId}/folders/{folderId}/recordings/{recordingId}

Idempotent. Requires read-write access to the folder. 404 if the recording does not exist in the directory.

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.

• folderIdstringrequired

  Id of the folder.

• recordingIdstringrequired

  Id of the recording.

Status codes

• 204Success
• 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.

Request

cURL

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

JavaScript

const response = await fetch(`https://api.sally.io/v1.0/directories/${directoryId}/folders/${folderId}/recordings/${recordingId}`, {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.SALLY_TOKEN}`,
  },
});
console.log(response.status); // 204

Python

import os
import requests

response = requests.put(
    f"https://api.sally.io/v1.0/directories/{directory_id}/folders/{folder_id}/recordings/{recording_id}",
    headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
)
print(response.status_code)  # 204

Response example 204 No Content

No content. A successful call returns an empty body.

Removes a recording from a folder

DELETE/v1.0/directories/{directoryId}/folders/{folderId}/recordings/{recordingId}

Requires read-write access to the folder.

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.

• folderIdstringrequired

  Id of the folder.

• recordingIdstringrequired

  Id of the recording.

Status codes

• 204Success
• 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.

Request

cURL

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

JavaScript

const response = await fetch(`https://api.sally.io/v1.0/directories/${directoryId}/folders/${folderId}/recordings/${recordingId}`, {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.SALLY_TOKEN}`,
  },
});
console.log(response.status); // 204

Python

import os
import requests

response = requests.delete(
    f"https://api.sally.io/v1.0/directories/{directory_id}/folders/{folder_id}/recordings/{recording_id}",
    headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
)
print(response.status_code)  # 204

Response example 204 No Content

No content. A successful call returns an empty body.