Microsoft Graph API Orchestration Skill
Microsoft Graph is a unified REST API endpoint for accessing Microsoft Cloud resources across Microsoft 365, Windows, and Enterprise Mobility + Security. Base URL: https://graph.microsoft.com/{version}/{resource}
API Versions: v1.0 (production) or beta (preview) Authentication: OAuth 2.0 via Azure AD Data Format: JSON
When to Load Which Resource Task Service Load Resource Setup auth, register apps, manage credentials Applications & Auth resources/authentication-apps.md Manage users, groups, organization, directory Identity & Access resources/identity-access.md Email, folders, attachments, rules, signatures Mail Operations resources/mail-operations.md Calendar, events, scheduling, meetings, free/busy Calendar & Scheduling resources/calendar-scheduling.md Upload files, folders, share, OneDrive, SharePoint Files & Storage resources/files-storage.md Teams, channels, chats, presence, online meetings Teams & Communications resources/teams-communications.md Planner tasks, To Do lists, OneNote notebooks Planning & Notes resources/planning-notes.md Security alerts, compliance, device management, reports Security & Governance resources/security-governance.md Orchestration Protocol Phase 1: Analyze Your Task
Identify which service area you need by answering:
What resource? (users, files, messages, events, etc.) What action? (read, create, update, delete) Who? (signed-in user or service account) Permissions? (delegated or application) Phase 2: Load the Right Resource
Use the decision table above to find your resource file. Each resource includes:
Complete endpoint reference with base paths Request/response examples for all CRUD operations Query parameters and filter options Required permissions (delegated and application) Error handling patterns and best practices Common workflows and patterns Phase 3: Implement with Confidence
Each resource shows practical, copy-paste-ready examples for your use case.
Universal Graph Concepts
Standard Query Parameters:
$select=prop1,prop2 Choose properties to return $filter=startsWith(name,'A') Filter results by condition $orderby=name desc Sort results (asc or desc) $top=25 Limit to 25 results (default 20) $skip=50 Skip first 50 results $expand=members Include related/nested data $count=true Include total count in response $search="keyword" Full-text search across content
Standard CRUD Operations:
GET /me/messages?$select=subject&$top=10 # Read POST /me/events {"subject": "Meeting", ...} # Create PATCH /users/{id} {"jobTitle": "Manager"} # Update DELETE /me/messages/{id} # Delete
Pagination: Always follow @odata.nextLink in responses for complete data sets
Batch Requests: Use POST /$batch to combine 1-20 operations into single call
Delta Queries: Use GET /users/delta to track changes since last query via @odata.deltaLink
Error Response Format:
{"error": {"code": "Code", "message": "Description"}}
Common Status Codes:
200/201/204: Success 400: Invalid request 401: Authentication required 403: Insufficient permissions 404: Resource not found 429: Rate limited (check Retry-After header) 500-503: Server error (implement exponential backoff) Resource File Index File Focus Lines authentication-apps.md App registration, OAuth, credentials 350+ identity-access.md Users, groups, organization, directory 350+ mail-operations.md Email, folders, attachments, rules 400+ calendar-scheduling.md Events, recurring, meetings, free/busy 350+ files-storage.md OneDrive, SharePoint, uploads, sharing 400+ teams-communications.md Teams, channels, chats, presence 350+ planning-notes.md Planner, To Do, OneNote 350+ security-governance.md Security, compliance, devices, reports 400+ Best Practices
Performance: Use $select for specific properties, implement pagination, cache tokens, use batch for bulk ops, apply delta queries for sync scenarios
Security: Store tokens securely (never in code), request least-privilege permissions, use managed identities for Azure, rotate credentials every 90 days, validate all responses
Development: Test in beta endpoint first, monitor deprecation notices, implement exponential backoff for retries, respect rate limiting, check Graph health status
Troubleshooting:
401 Unauthorized → Check token validity and scopes 403 Forbidden → Verify permissions are configured in Azure AD 404 Not Found → Verify resource ID and that resource exists 429 Too Many Requests → Implement retry with exponential backoff Tools & SDK Resources
Interactive Testing: Graph Explorer at https://developer.microsoft.com/graph/graph-explorer
SDKs:
.NET: Microsoft.Graph NuGet JavaScript/TypeScript: @microsoft/microsoft-graph-client npm Python: msgraph-sdk-python pip
Documentation:
API Reference: https://docs.microsoft.com/graph/api/overview Permissions Reference: https://docs.microsoft.com/graph/permissions-reference Changelog: https://docs.microsoft.com/graph/changelog
Skill Version: 2.1 | API Versions: v1.0 (production), beta (preview) | Updated: December 2025