Skill: byungkyu/one-drive (version 1.0.5)

--- name: one-drive description: | OneDrive API integration with managed OAuth via Microsoft Graph. Manage files, folders, and sharing. Use this skill when users want to upload, download, organize, or share files in OneDrive. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway). Requires network access and valid Maton API key. metadata: author: maton version: "1.0" clawdbot: emoji: 🧠 requires: env: - MATON_API_KEY --- # OneDrive Access the OneDrive API with managed OAuth authentication via Microsoft Graph. Manage files, folders, drives, and sharing with full CRUD operations. ## Quick Start **CLI:** ```bash maton one-drive item list ``` ```bash maton api '/one-drive/v1.0/me/drive/root/children' ``` **Python:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://api.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://api.maton.ai/one-drive/v1.0/{resource} ``` Maton proxies requests to `graph.microsoft.com` and automatically injects your OAuth token. ## Installation **NPM:** ```bash npm install -g @maton-ai/cli ``` **Homebrew:** ```bash brew install maton-ai/cli/maton ``` ## Authentication **CLI:** ```bash maton login # Opens browser for API key maton login --interactive # Skip browser, paste API key directly maton whoami # Show current auth state ``` **Manual:** 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 4. Set your API key as `MATON_API_KEY`: ```bash export MATON_API_KEY="YOUR_API_KEY" ``` ## Connection Management Manage your OneDrive OAuth connections at `https://api.maton.ai`. ### List Connections **CLI:** ```bash maton connection list one-drive --status ACTIVE ``` ```bash maton api -X GET /connections -f app=one-drive -f status=ACTIVE ``` **Python:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://api.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 **CLI:** ```bash maton connection create one-drive ``` ```bash maton api /connections -f app=one-drive ``` **Python:** ```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'one-drive'}).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 **CLI:** ```bash maton connection view {connection_id} ``` ```bash maton api /connections/{connection_id} ``` **Python:** ```bash 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:** ```json { "connection": { "connection_id": "{connection_id}", "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 **CLI:** ```bash maton connection delete {connection_id} ``` ```bash maton api -X DELETE /connections/{connection_id} ``` **Python:** ```bash 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 ``` ### Specifying Connection If you have multiple OneDrive connections, specify which one to use: **CLI:** ```bash maton one-drive item list --connection {connection_id} ``` ```bash maton api /one-drive/v1.0/me/drive/root/children --connection {connection_id} ``` **Python:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://api.maton.ai/one-drive/v1.0/me/drive') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', '{connection_id}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` If you have multiple connections, always specify the connection to ensure requests go to the intended account. ## Security & Permissions - Access is scoped to files, folders, and sharing within the connected OneDrive 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 ### Drives #### Get Current User's Drive ```bash GET /one-drive/v1.0/me/drive ``` Example: ```bash maton one-drive whoami ``` #### List User's Drives ```bash GET /one-drive/v1.0/me/drives ``` Example: ```bash maton one-drive drive list ``` #### Get Drive by ID ```bash GET /one-drive/v1.0/drives/{drive-id} ``` Example: ```bash maton one-drive drive view {drive-id} ``` ### Files and Folders #### Get Drive Root ```bash GET /one-drive/v1.0/me/drive/root ``` Example: ```bash maton one-drive item view root ``` #### List Root Children ```bash GET /one-drive/v1.0/me/drive/root/children ``` Example: ```bash maton one-drive item list ``` #### Get Item by ID ```bash GET /one-drive/v1.0/me/drive/items/{item-id} ``` Example: ```bash maton one-drive item view {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 ``` Example: ```bash maton one-drive item view-by-path Documents/report.pdf ``` #### List Folder Children by Path ```bash GET /one-drive/v1.0/me/drive/root:/Documents:/children ``` Example: ```bash maton one-drive item list Documents ``` #### Get Item Children ```bash GET /one-drive/v1.0/me/drive/items/{item-id}/children ``` Example: ```bash maton one-drive item view {item-id} --expand 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 ``` Example: ```bash maton one-drive item view --special documents ``` ### Recent and Shared #### Get Recent Files ```bash GET /one-drive/v1.0/me/drive/recent ``` Example: ```bash maton one-drive drive recent ``` #### Get Files Shared With Me ```bash GET /one-drive/v1.0/me/drive/sharedWithMe ``` Example: ```bash maton one-drive drive shared ``` ### Search ```bash GET /one-drive/v1.0/me/drive/root/search(q='budget') ``` Example: ```bash maton one-drive drive search 'budget' ``` ### Create Folder ```bash POST /one-drive/v1.0/me/drive/root:/Documents:/children Content-Type: application/json { "name": "Reports", "folder": {}, "@microsoft.graph.conflictBehavior": "rename" } ``` Example: ```bash maton one-drive item create-folder Reports --path Documents ``` Create folder inside another folder by parent ID: ```bash POST /one-drive/v1.0/me/drive/items/{parent-id}/children Content-Type: application/json { "name": "Reports", "folder": {} } ``` Example: ```bash maton one-drive item create-folder Reports --parent-id {parent-id} ``` ### Upload File (Simple - up to 4MB) ```bash PUT /one-drive/v1.0/me/drive/root:/Documents/report.pdf:/content Content-Type: application/pdf {report.pdf binary content} ``` Example: ```bash maton one-drive item upload ./report.pdf --path Documents/report.pdf ``` ### 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:/large-report.pdf:/createUploadSession Content-Type: application/json { "item": { "@microsoft.graph.conflictBehavior": "rename" } } ``` Example: ```bash maton one-drive item upload ./large-report.pdf --path large-report.pdf --conflict rename ``` Files larger than 4 MiB automatically use a resumable upload session. **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} ``` Example: ```bash maton one-drive item view {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" } ``` Example: ```bash maton one-drive item update {item-id} --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}" } } ``` Example: ```bash maton one-drive item move {item-id} --dest-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" } ``` Example: ```bash maton one-drive item copy {item-id} --dest-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} ``` Example: ```bash maton one-drive item delete {item-id} ``` Returns `204 No Content` on success. ### Sharing #### Create Sharing Link ```bash POST /one-drive/v1.0/me/drive/items/01ABCDEF/createLink Content-Type: application/json { "type": "view", "scope": "anonymous" } ``` Link types: - `view` - Read-only access - `edit` - Read-write access - `embed` - Embeddable link Scopes: - `anonymous` - Anyone with the link - `organization` - Anyone in your organization Example: ```bash maton one-drive item share 01ABCDEF --type view --scope anonymous ``` #### Invite Users (Share with specific people) ```bash POST /one-drive/v1.0/me/drive/items/{item-id}/invite Content-Type: application/json { "recipients": [ {"email": "[REDACTED_SECRET]"} ], "roles": ["read"], "sendInvitation": true, "message": "Check out this file!" } ``` Example: ```bash maton one-drive item invite {item-id} --emails [REDACTED_SECRET] --roles read --message 'Check out this file!' ``` ## Query Parameters Customize responses with OData query parameters: - `$select` - Choose specific properties: `?$select=id,name,size` - `$expand` - Include related resources: `?$expand=children` - `$filter` - Filter results: `?$filter=file ne null` (files only) - `$orderby` - Sort results: `?$orderby=name asc` - `$top` - Limit results: `?$top=10` Example: ```bash GET /one-drive/v1.0/me/drive/root/children?$select=id,name,size&$top=20&$orderby=name%20asc ``` ```bash maton one-drive item list --select id,name,size --top 20 --orderby 'name asc' ``` ## Pagination OneDrive uses cursor-based pagination. The CLI automatically paginates with '--paginate'. Example: ```bash maton one-drive item list --paginate ``` ## Code Examples ### CLI ```bash # Search for files maton one-drive drive search 'budget' # Share a file maton one-drive item share 01ABCDEF --type view --scope anonymous # Extract specific fields with --jq (requires --json) maton one-drive item view root --json --jq '.name' ``` ### JavaScript ```javascript // List files in root const response = await fetch( 'https://api.maton.ai/one-drive/v1.0/me/drive/root/children', { headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}` } } ); const data = await response.json(); // Upload a file const uploadResponse = await fetch( 'https://api.maton.ai/one-drive/v1.0/me/drive/root:/myfile.txt:/content', { method: 'PUT', headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}`, 'Content-Type': 'text/plain' }, body: 'Hello, OneDrive!' } ); ``` ### Python ```python import os import requests # List files in root response = requests.get( 'https://api.maton.ai/one-drive/v1.0/me/drive/root/children', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'} ) files = response.json() # Upload a file upload_response = requests.put( 'https://api.maton.ai/one-drive/v1.0/me/drive/root:/myfile.txt:/content', headers={ 'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}', 'Content-Type': 'text/plain' }, data='Hello, OneDrive!' ) ``` ## Notes - OneDrive uses Microsoft Graph API (`graph.microsoft.com`) - Item IDs are unique within a drive - Use colon (`:`) syntax for path-based addressing: `/root:/path/to/file` - Files ≤4MB upload via a single PUT; larger files automatically use a resumable upload session - Download URLs from `@microsoft.graph.downloadUrl` are pre-authenticated and temporary - Conflict behavior options: `fail`, `replace`, `rename` - On personal OneDrive accounts, only the user's own drive ID (returned by `whoami`) is directly addressable. The additional `b!...`-prefixed IDs that appear in `drive list` return HTTP 400 from Microsoft Graph when fetched this way. Use `me/drive` instead. - IMPORTANT: When using curl commands, use `curl -g` when URLs contain brackets to disable glob parsing - IMPORTANT: When piping curl output to `jq` or other commands, environment variables like `$MATON_API_KEY` may not expand correctly in some shell environments ## Error Handling | Status | Meaning | |--------|---------| | 400 | Missing OneDrive connection or invalid request | | 401 | Invalid or missing Maton API key | | 403 | Insufficient permissions | | 404 | Item not found | | 409 | Conflict (e.g., item already exists) | | 429 | Rate limited (check `Retry-After` header) | | 4xx/5xx | Passthrough error from Microsoft Graph API | ### Error Response Format ```json { "error": { "code": "itemNotFound", "message": "The resource could not be found." } } ``` ### Troubleshooting: API Key Issues **CLI:** 1. Check your auth state: ```bash maton whoami ``` 2. Verify the API key is valid by listing connections: ```bash maton connection list ``` **Manual:** 1. Check that the `MATON_API_KEY` environment variable is set: ```bash echo $MATON_API_KEY ``` 2. Verify the API key is valid by listing connections: ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://api.maton.ai/connections') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Troubleshooting: Invalid App Name 1. Ensure your URL path starts with `one-drive`. For example: - Correct: `https://api.maton.ai/one-drive/v1.0/me/drive/root/children` - Incorrect: `https://api.maton.ai/v1.0/me/drive/root/children` ## Resources - [OneDrive Developer Documentation](https://learn.microsoft.com/en-us/onedrive/developer/) - [Microsoft Graph API Reference](https://learn.microsoft.com/en-us/graph/api/overview) - [DriveItem Resource](https://learn.microsoft.com/en-us/graph/api/resources/driveitem) - [Drive Resource](https://learn.microsoft.com/en-us/graph/api/resources/drive) - [Sharing and Permissions](https://learn.microsoft.com/en-us/onedrive/developer/rest-api/concepts/sharing) - [Large File Upload](https://learn.microsoft.com/en-us/graph/api/driveitem-createuploadsession) - [Maton CLI Manual](https://cli.maton.ai/manual) - [Maton Community](https://discord.com/invite/dBfFAcefs2) - [Maton Support](mailto:[REDACTED_SECRET])


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)