sharepoint（sharepoint 文档）

SharePoint

Access SharePoint via Microsoft Graph API with managed OAuth authentication.

Quick Start

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/sharepoint/v1.0/sites/root')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Base URL

https://api.maton.ai/sharepoint/{native-api-path}

Maton proxies requests to graph.microsoft.com and automatically injects your OAuth token.

Authentication

All requests require the Maton API key:

Authorization: Bearer $MATON_API_KEY

Environment Variable: Set your API key as MATON_API_KEY:

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

1. Sign in or create an account at maton.ai
2. Go to maton.ai/settings
3. Copy your API key

Connection Management

Manage your SharePoint OAuth connections at https://api.maton.ai.

List Connections

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections?app=sharepoint&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Create Connection

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'sharepoint'}).encode()
req = urllib.request.Request('https://api.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Get Connection

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "connection": {
    "connection_id": "{connection_id}",
    "status": "PENDING",
    "creation_time": "2026-03-05T08:00:00.000000Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "sharepoint",
    "method": "OAUTH2",
    "metadata": {}
  }
}

Open the returned url in a browser to complete OAuth authorization.

Delete Connection

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Security & Permissions

• Access is scoped to SharePoint sites, lists, document libraries, and files within the connected SharePoint account.
• All write operations require explicit user approval. Before executing any create, update, or delete call, confirm the target resource and intended effect with the user.

API Reference

Sites

Get Root Site

GET /sharepoint/v1.0/sites/root

Response:

{
  "id": "contoso.sharepoint.com,guid1,guid2",
  "displayName": "Communication site",
  "name": "root",
  "webUrl": "https://contoso.sharepoint.com"
}

Get Site by ID

GET /sharepoint/v1.0/sites/{site_id}

Site IDs follow the format: {hostname},{site-guid},{web-guid}

Get Site by Hostname and Path

GET /sharepoint/v1.0/sites/{hostname}:/{site-path}

Example: GET /sharepoint/v1.0/sites/contoso.sharepoint.com:/sites/marketing

Search Sites

GET /sharepoint/v1.0/sites?search={query}

List Subsites

GET /sharepoint/v1.0/sites/{site_id}/sites

Get Site Columns

GET /sharepoint/v1.0/sites/{site_id}/columns

Get Followed Sites

GET /sharepoint/v1.0/me/followedSites

Lists

List Site Lists

GET /sharepoint/v1.0/sites/{site_id}/lists

Response:

{
  "value": [
    {
      "id": "b23974d6-a0aa-4e9b-9535-25393598b973",
      "name": "Events",
      "displayName": "Events",
      "webUrl": "https://contoso.sharepoint.com/Lists/Events"
    }
  ]
}

Get List

GET /sharepoint/v1.0/sites/{site_id}/lists/{list_id}

List Columns

GET /sharepoint/v1.0/sites/{site_id}/lists/{list_id}/columns

List Content Types

GET /sharepoint/v1.0/sites/{site_id}/lists/{list_id}/contentTypes

List Items

GET /sharepoint/v1.0/sites/{site_id}/lists/{list_id}/items

With field values (use $expand=fields):

GET /sharepoint/v1.0/sites/{site_id}/lists/{list_id}/items?$expand=fields

Response:

{
  "value": [
    {
      "id": "1",
      "createdDateTime": "2026-03-05T08:00:00Z",
      "fields": {
        "Title": "Team Meeting",
        "EventDate": "2026-03-10T14:00:00Z",
        "Location": "Conference Room A"
      }
    }
  ]
}

Get List Item

GET /sharepoint/v1.0/sites/{site_id}/lists/{list_id}/items/{item_id}?$expand=fields

Create List Item

POST /sharepoint/v1.0/sites/{site_id}/lists/{list_id}/items
Content-Type: application/json

{
  "fields": {
    "Title": "New Event",
    "EventDate": "2026-04-01T10:00:00Z",
    "Location": "Main Hall"
  }
}

Update List Item

PATCH /sharepoint/v1.0/sites/{site_id}/lists/{list_id}/items/{item_id}/fields
Content-Type: application/json

{
  "Title": "Updated Event Title"
}

Delete List Item

DELETE /sharepoint/v1.0/sites/{site_id}/lists/{list_id}/items/{item_id}

Returns 204 No Content on success.

Drives (Document Libraries)

List Site Drives

GET /sharepoint/v1.0/sites/{site_id}/drives

Get Default Drive

GET /sharepoint/v1.0/sites/{site_id}/drive

Get Drive by ID

GET /sharepoint/v1.0/drives/{drive_id}

Note: Drive IDs containing ! (e.g., b!abc123) must be URL-encoded: b%21abc123

Files and Folders

List Root Contents

GET /sharepoint/v1.0/drives/{drive_id}/root/children

Response:

{
  "value": [
    {
      "id": "01WBMXT7NQEEYJ3BAXL5...",
      "name": "Documents",
      "folder": { "childCount": 5 },
      "webUrl": "https://contoso.sharepoint.com/Shared%20Documents/Documents"
    },
    {
      "id": "01WBMXT7LISS5OMIG4CZ...",
      "name": "report.docx",
      "file": { "mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document" },
      "size": 25600
    }
  ]
}

Get Item by ID

GET /sharepoint/v1.0/drives/{drive_id}/items/{item_id}

Get Item by Path

GET /sharepoint/v1.0/drives/{drive_id}/root:/{path}

Example: GET /sharepoint/v1.0/drives/{drive_id}/root:/Reports/Q1.xlsx

List Folder Contents

GET /sharepoint/v1.0/drives/{drive_id}/items/{folder_id}/children

Or by path:

GET /sharepoint/v1.0/drives/{drive_id}/root:/{folder_path}:/children

Download File

GET /sharepoint/v1.0/drives/{drive_id}/items/{item_id}/content

Or by path:

GET /sharepoint/v1.0/drives/{drive_id}/root:/{path}:/content

Returns a redirect to the download URL (follow redirects to get file content).

Upload File (Simple - up to 4MB)

PUT /sharepoint/v1.0/drives/{drive_id}/root:/{filename}:/content
Content-Type: application/octet-stream

<file content>

Example:

curl -X PUT "https://api.maton.ai/sharepoint/v1.0/drives/{drive_id}/root:/documents/report.txt:/content" \
  -H "Authorization: Bearer $MATON_API_KEY" \
  -H "Content-Type: text/plain" \
  -d "File content here"

Create Folder

POST /sharepoint/v1.0/drives/{drive_id}/root/children
Content-Type: application/json

{
  "name": "New Folder",
  "folder": {},
  "@microsoft.graph.conflictBehavior": "rename"
}

Or in a specific folder:

POST /sharepoint/v1.0/drives/{drive_id}/items/{parent_id}/children

Rename/Move Item

PATCH /sharepoint/v1.0/drives/{drive_id}/items/{item_id}
Content-Type: application/json

{
  "name": "new-filename.txt"
}

To move to another folder:

PATCH /sharepoint/v1.0/drives/{drive_id}/items/{item_id}
Content-Type: application/json

{
  "parentReference": {
    "id": "{target_folder_id}"
  }
}

Copy Item

POST /sharepoint/v1.0/drives/{drive_id}/items/{item_id}/copy
Content-Type: application/json

{
  "name": "copied-file.txt"
}

This is an async operation - returns 202 Accepted with a Location header for progress tracking.

Delete Item

DELETE /sharepoint/v1.0/drives/{drive_id}/items/{item_id}

Returns 204 No Content on success. Deleted items go to the recycle bin.

Search Files

GET /sharepoint/v1.0/drives/{drive_id}/root/search(q='{query}')

Response:

{
  "value": [
    {
      "id": "01WBMXT7...",
      "name": "quarterly-report.xlsx",
      "webUrl": "https://contoso.sharepoint.com/..."
    }
  ]
}

Track Changes (Delta)

GET /sharepoint/v1.0/drives/{drive_id}/root/delta

Returns changed items and a @odata.deltaLink for subsequent requests.

Sharing and Permissions

Get Item Permissions

GET /sharepoint/v1.0/drives/{drive_id}/items/{item_id}/permissions

Create Sharing Link

POST /sharepoint/v1.0/drives/{drive_id}/items/{item_id}/createLink
Content-Type: application/json

{
  "type": "view",
  "scope": "organization"
}

Parameters:

• type: view, edit, or embed
• scope: anonymous, organization, or users

Response:

{
  "id": "f0cfb2bd-ef5f-4451-9932-8e9a3e219aaa",
  "roles": ["read"],
  "link": {
    "type": "view",
    "scope": "organization",
    "webUrl": "https://contoso.sharepoint.com/:t:/g/..."
  }
}

Versions

List File Versions

GET /sharepoint/v1.0/drives/{drive_id}/items/{item_id}/versions

Response:

{
  "value": [
    {
      "id": "2.0",
      "lastModifiedDateTime": "2026-03-05T08:07:12Z",
      "size": 25600,
      "lastModifiedBy": {
        "user": { "displayName": "John Doe" }
      }
    },
    {
      "id": "1.0",
      "lastModifiedDateTime": "2026-03-04T10:00:00Z",
      "size": 24000
    }
  ]
}

Get Specific Version

GET /sharepoint/v1.0/drives/{drive_id}/items/{item_id}/versions/{version_id}

Download Version Content

GET /sharepoint/v1.0/drives/{drive_id}/items/{item_id}/versions/{version_id}/content

Thumbnails

Get Item Thumbnails

GET /sharepoint/v1.0/drives/{drive_id}/items/{item_id}/thumbnails

Response:

{
  "value": [
    {
      "id": "0",
      "small": { "height": 96, "width": 96, "url": "..." },
      "medium": { "height": 176, "width": 176, "url": "..." },
      "large": { "height": 800, "width": 800, "url": "..." }
    }
  ]
}

OData Query Parameters

SharePoint/Graph API supports OData query parameters:

Example with multiple parameters:

GET /sharepoint/v1.0/sites/{site_id}/lists/{list_id}/items?$expand=fields&$top=50&$orderby=createdDateTime desc

Code Examples

JavaScript

const response = await fetch('https://api.maton.ai/sharepoint/v1.0/sites/root', {
  headers: {
    'Authorization': `Bearer ${process.env.MATON_API_KEY}`
  }
});
const data = await response.json();
console.log(data);

Python

import os
import requests

response = requests.get(
    'https://api.maton.ai/sharepoint/v1.0/sites/root',
    headers={
        'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'
    }
)
print(response.json())

Notes

• Site IDs follow the format: {hostname},{site-guid},{web-guid}
• Drive IDs with ! (e.g., b!abc123) must be URL-encoded (b%21abc123)
• Item IDs are opaque strings (e.g., 01WBMXT7NQEEYJ3BAXL5...)
• File uploads via PUT are limited to 4MB; use upload sessions for larger files
• Copy operations are asynchronous - check the Location header for progress
• Deleted items go to the SharePoint recycle bin
• Some admin operations require elevated permissions (Sites.FullControl.All)

Error Handling

Resources

• SharePoint Sites API
• DriveItem API
• List API
• Microsoft Graph Explorer
• Maton Community
• Maton Support