SharePoint Integration

List, download, and manage files programmatically with SharePoint integration and Microsoft Graph API.

---

Timbal integrates with SharePoint to enable listing, downloading, and managing files programmatically.

This integration allows you to access both personal and shared files across different scopes in your SharePoint environment.

Prerequisites

Before using the SharePoint integration, you'll need:

1. A Microsoft 365 tenant
2. A registered application in Azure Portal with:
   • Application (client) ID
   • Directory (tenant) ID
   • Client secret
3. Required permissions configured:
   • Files.Read.All
   • Sites.Read.All
4. A token_sharepoint.json file with your credentials

Authentication Setup

The first time you use the integration, you'll be prompted to authenticate:

uv run authenticate.py

This will open a browser window for Microsoft sign-in and create a token file for future use.

Installation

Install the requirements by doing:

uv add timbal[steps-sharepoint]

List Directory

Description

The list_directory step allows you to list files and folders in SharePoint, with support for both personal and shared files across different scopes.

Example

from timbal.steps.sharepoint.directories import list_directory

# List all files in personal drive
items = await list_directory(scope="my-files")

# List contents of a specific folder
folder_items = await list_directory(
  folder="Projects/2024",
  scope="my-files"
)

# List shared files
shared_items = await list_directory(scope="shared")

Parameters

Parameter	Type	Description	Required
folder	str	The SharePoint folder path to list contents from	No
scope	str	Where to search for files: 'my-files', 'shared', or 'all'	No
output_path	str	Path to save the output JSON file	No

Download File

Description

The download_file step allows you to download files from SharePoint by searching for them across different scopes.

Example

from timbal.steps.sharepoint.files import download_file

# Download a file from personal drive
success = await download_file("document.docx")

# Download from a specific folder
success = await download_file(
  "report.pdf",
  folder="Projects/2024"
)

# Download from shared files
success = await download_file(
  "presentation.pptx",
  scope="shared"
)

# Download to specific location
success = await download_file(
  "data.xlsx",
  destination="/path/to/save"
)

Parameters

Parameter	Type	Description	Required
file	str	Name or ID of the file to find and download	Yes
destination	str	Directory where the file will be downloaded to. If None, uses the current working directory	No
folder	str	Optional path to a specific folder to search in	No
scope	str	Search scope ('my-files', 'shared', or 'all'). Defaults to 'my-files'	No

Agent Integration Example

from timbal.steps.sharepoint.directories import list_directory
from timbal import Agent

agent = Agent(
  tools=[list_directory]
)

response = await agent.complete(
  prompt={
      "folder": "Projects/2024",
      "scope": "my-files"
  }
)

Notes

• Make sure your Microsoft 365 tenant and app registration are properly configured
• The first authentication will prompt a browser sign-in and create a token file for future use
• File names are case-sensitive
• If multiple files with the same name exist, an error will be raised
• Ensure you have the necessary permissions to access the files
• For more advanced usage, see the Microsoft Graph API documentation