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://gateway.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://gateway.maton.ai/sharepoint/{native-api-path}

The gateway 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://ctrl.maton.ai.

List Connections

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.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://ctrl.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://ctrl.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": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
    "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://ctrl.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

---

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://gateway.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:

Parameter	Description	Example
$select	Select specific properties	?$select=id,name,size
$expand	Expand related entities	?$expand=fields
$filter	Filter results	?$filter=name eq 'Report'
$orderby	Sort results	?$orderby=lastModifiedDateTime desc
$top	Limit results	?$top=10
$skip	Skip results (pagination)	?$skip=10

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://gateway.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://gateway.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

Status	Meaning
200	Success
201	Created
202	Accepted (async operation started)
204	No Content (successful delete)
400	Bad request / Invalid JSON
401	Invalid or missing authentication
403	Access denied / Insufficient permissions
404	Resource not found
409	Conflict (e.g., item already exists)
429	Rate limited

Resources

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