SharePoint

---

name: sharepoint

description: |

SharePoint API integration via Microsoft Graph with managed OAuth. Access SharePoint sites, lists, document libraries, and files.

Use this skill when users want to interact with SharePoint for document management, list operations, or site content.

For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway).

compatibility: Requires network access and valid Maton API key

metadata:

author: maton

version: "1.0"

clawdbot:

emoji:

homepage: "https://maton.ai"

requires:

env:

- MATON_API_KEY

---

# 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](https://maton.ai)

2. Go to [maton.ai/settings](https://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:**

**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

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