one-drive

# OneDrive Access the OneDrive API with managed OAuth authentication via Microsoft Graph. Manage files, folders, drives, and sharing with full CRUD operations. ## Quick Start ```bash # List files in OneDrive root python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/one-drive/v1.0/me/drive/root/children') 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/one-drive/v1.0/{resource} ``` The gateway proxies requests to `graph.microsoft.com` and automatically injects your OAuth token. ## Authentication All requests require the Maton API key in the Authorization header: ``` Authorization: Bearer $MATON_API_KEY ``` **Environment Variable:** Set your API key as `MATON_API_KEY`: ```bash 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 OneDrive OAuth connections at `https://ctrl.maton.ai`. ### List Connections ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=one-drive&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 ```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'one-drive'}).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 ```bash 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:** ```json { "connection": { "connection_id": "3f17fb58-4515-4840-8ef6-2bbf0fa67e2c", "status": "ACTIVE", "creation_time": "2026-02-07T08:23:30.317909Z", "last_updated_time": "2026-02-07T08:24:04.925298Z", "url": "https://connect.maton.ai/?session_token=...", "app": "one-drive", "metadata": {} } } ``` Open the returned `url` in a browser to complete OAuth authorization. ### Delete Connection ```bash 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 ``` ### Specifying Connection If you have multiple OneDrive connections, specify which one to use with the `Maton-Connection` header: ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/one-drive/v1.0/me/drive') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', '3f17fb58-4515-4840-8ef6-2bbf0fa67e2c') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` If omitted, the gateway uses the default (oldest) active connection. ## API Reference ### Drives #### Get Current User's Drive ```bash GET /one-drive/v1.0/me/drive ``` **Response:** ```json { "id": "b!F3Y7M0VT80OO9iu_D6Z-LA...", "driveType": "personal", "name": "OneDrive", "owner": { "user": { "displayName": "John Doe", "id": "d4648f06c91d9d3d" } }, "quota": { "total": 5368709120, "used": 1234567, "remaining": 5367474553 } } ``` #### List User's Drives ```bash GET /one-drive/v1.0/me/drives ``` #### Get Drive by ID ```bash GET /one-drive/v1.0/drives/{drive-id} ``` ### Files and Folders #### Get Drive Root ```bash GET /one-drive/v1.0/me/drive/root ``` #### List Root Children ```bash GET /one-drive/v1.0/me/drive/root/children ``` **Response:** ```json { "value": [ { "id": "F33B7653325337C3!s88...", "name": "Documents", "folder": { "childCount": 5 }, "createdDateTime": "2024-01-15T10:30:00Z", "lastModifiedDateTime": "2024-02-01T14:20:00Z" }, { "id": "F33B7653325337C3!s3f...", "name": "report.pdf", "file": { "mimeType": "application/pdf", "hashes": { "sha1Hash": "cf23df2207d99a74fbe169e3eba035e633b65d94" } }, "size": 35212 } ] } ``` #### Get Item by ID ```bash GET /one-drive/v1.0/me/drive/items/{item-id} ``` #### Get Item by Path Use colon (`:`) syntax to access items by path: ```bash GET /one-drive/v1.0/me/drive/root:/Documents/report.pdf ``` #### List Folder Children by Path ```bash GET /one-drive/v1.0/me/drive/root:/Documents:/children ``` #### Get Item Children ```bash GET /one-drive/v1.0/me/drive/items/{item-id}/children ``` ### Special Folders Access known folders by name: ```bash GET /one-drive/v1.0/me/drive/special/documents GET /one-drive/v1.0/me/drive/special/photos GET /one-drive/v1.0/me/drive/special/music GET /one-drive/v1.0/me/drive/special/approot ``` ### Recent and Shared #### Get Recent Files ```bash GET /one-drive/v1.0/me/drive/recent ``` #### Get Files Shared With Me ```bash GET /one-drive/v1.0/me/drive/sharedWithMe ``` ### Search ```bash GET /one-drive/v1.0/me/drive/root/search(q='{query}') ``` Example: ```bash GET /one-drive/v1.0/me/drive/root/search(q='budget') ``` ### Create Folder ```bash POST /one-drive/v1.0/me/drive/root/children Content-Type: application/json { "name": "New Folder", "folder": {}, "@microsoft.graph.conflictBehavior": "rename" } ``` Create folder inside another folder: ```bash POST /one-drive/v1.0/me/drive/items/{parent-id}/children Content-Type: application/json { "name": "Subfolder", "folder": {} } ``` ### Upload File (Simple - up to 4MB) ```bash PUT /one-drive/v1.0/me/drive/items/{parent-id}:/{filename}:/content Content-Type: application/octet-stream {file binary content} ``` Example - upload to root: ```bash PUT /one-drive/v1.0/me/drive/root:/document.txt:/content Content-Type: text/plain Hello, OneDrive! ``` ### Upload File (Large - resumable) For files over 4MB, use resumable upload: **Step 1: Create upload session** ```bash POST /one-drive/v1.0/me/drive/root:/{filename}:/createUploadSession Content-Type: application/json { "item": { "@microsoft.graph.conflictBehavior": "rename" } } ``` **Response:** ```json { "uploadUrl": "https://sn3302.up.1drv.com/up/...", "expirationDateTime": "2024-02-08T10:00:00Z" } ``` **Step 2: Upload bytes to the uploadUrl** ### Download File Get the file metadata to retrieve the download URL: ```bash GET /one-drive/v1.0/me/drive/items/{item-id} ``` The response includes `@microsoft.graph.downloadUrl` - a pre-authenticated URL valid for a short time: ```json { "id": "...", "name": "document.pdf", "@microsoft.graph.downloadUrl": "https://public-sn3302.files.1drv.com/..." } ``` Use this URL directly to download the file content (no auth header needed). ### Update Item (Rename/Move) ```bash PATCH /one-drive/v1.0/me/drive/items/{item-id} Content-Type: application/json { "name": "new-name.txt" } ``` Move to different folder: ```bash PATCH /one-drive/v1.0/me/drive/items/{item-id} Content-Type: application/json { "parentReference": { "id": "{new-parent-id}" } } ``` ### Copy Item ```bash POST /one-drive/v1.0/me/drive/items/{item-id}/copy Content-Type: application/json { "parentReference": { "id": "{destination-folder-id}" }, "name": "copied-file.txt" } ``` Returns `202 Accepted` with a `Location` header to monitor the copy operation. ### Delete Item ```bash DELETE /one-drive/v1.0/me/drive/items/{item-id} ```