Skip to main content

Folders API

Manage folders for organizing transcription sessions and documents.

Overview​

The Folders API allows you to create and list folders programmatically. Files uploaded with a folder ID will be organized under that folder in the Scriptix UI.

Base URL​

https://<instance>/api/v3/folders

Authentication​

Include your API key in the request header:

x-zoom-s2t-key: <api_key>

Endpoints​

MethodEndpointDescription
GET/api/v3/foldersList all folders
POST/api/v3/foldersCreate a new folder

TypeScript Types​

Folder​

type Folder = {
  id: number;
  name: string;
  created_at: string;
};

FolderPermission​

type FolderPermission = {
  group_id: number | null;
  permission: number;
};

CreateFolderRequest​

type CreateFolderRequest = {
  name: string;
  permissions: FolderPermission[];
};

CreateFolderResponse​

type CreateFolderResponse = {
  result: {
    id: number;
    name: string;
  };
};

ListFoldersResponse​

type ListFoldersResponse = {
  result: {
    folders: Folder[];
  };
};

List Folders​

Retrieve all folders for the organization.

Endpoint​

GET /api/v3/folders

Response​

{
  "result": {
    "folders": [
      {
        "id": 42,
        "name": "my-folder",
        "created_at": "2026-03-28T10:00:00Z"
      }
    ]
  }
}

Create Folder​

Create a new folder.

Endpoint​

POST /api/v3/folders

Request Headers​

Content-Type: application/json
x-zoom-s2t-key: <api_key>

Request Body​

{
  "name": "meeting-abc-def-ghi",
  "permissions": [
    {
      "group_id": null,
      "permission": 2
    }
  ]
}

Request Fields​

FieldTypeRequiredDescription
namestringYesFolder name
permissionsFolderPermission[]YesFolder permissions array
permissions[].group_idnumber | nullYesGroup ID or null for default access
permissions[].permissionnumberYesPermission level (2 = default access)

Response​

{
  "result": {
    "id": 43,
    "name": "meeting-abc-def-ghi"
  }
}

Assign Folder on Upload​

When uploading files via TUS, pass the folder_id in the upload metadata:

Upload-Metadata: ...,folder_id <base64(folder_id)>

The uploaded file and resulting transcription session will be organized under that folder in the Scriptix UI.

Notes​

  • The permissions field is required when creating a folder. Omitting it returns a 422 error.
  • Use group_id: null with permission: 2 for default access.
  • Folder names are not unique-enforced server-side. Check existing folders before creating to avoid duplicates.
  • Your API key must have folder permissions enabled, otherwise requests will return 401.
  • Cache folder IDs in your application to avoid repeated list calls.