microsoft-graph-skill/references/graph-api.md

Microsoft Graph API Reference

Base URL

https://graph.microsoft.com/v1.0

Authentication

Uses OAuth 2.0 device code flow for personal Microsoft accounts.

Endpoints

• Device code: https://login.microsoftonline.com/consumers/oauth2/v2.0/devicecode
• Token: https://login.microsoftonline.com/consumers/oauth2/v2.0/token

Scopes

• Mail.Read — Read emails
• Mail.Send — Send emails
• Files.ReadWrite — OneDrive access
• User.Read — User profile
• offline_access — Refresh tokens

Mail API

List messages

GET /me/mailFolders/inbox/messages?$top=10&$orderby=receivedDateTime desc

Read message

GET /me/messages/{id}

Send message

POST /me/sendMail
{
  "message": {
    "subject": "Subject",
    "body": {"contentType": "Text", "content": "Body"},
    "toRecipients": [{"emailAddress": {"address": "to@example.com"}}]
  }
}

Search messages

GET /me/messages?$search="from:sender@example.com"

List folders

GET /me/mailFolders

OneDrive API

List root

GET /me/drive/root/children

List folder

GET /me/drive/root:/{path}:/children

Get file metadata

GET /me/drive/root:/{path}

Download file

Get the @microsoft.graph.downloadUrl from file metadata.

Upload small file (<4MB)

PUT /me/drive/root:/{path}:/content
Content-Type: application/octet-stream

<file bytes>

Create folder

POST /me/drive/root/children
{
  "name": "New Folder",
  "folder": {}
}

Calendar API

List events

GET /me/events?$top=10&$orderby=start/dateTime

Create event

POST /me/events
{
  "subject": "Meeting",
  "start": {"dateTime": "2026-03-24T10:00:00", "timeZone": "Europe/Copenhagen"},
  "end": {"dateTime": "2026-03-24T11:00:00", "timeZone": "Europe/Copenhagen"}
}

Error Handling

Common errors:

• 401 Unauthorized — Token expired, need to refresh or re-auth
• 403 Forbidden — Missing permissions
• 404 NotFound — Resource doesn't exist
• 429 TooManyRequests — Rate limited, back off

Rate Limits

• Per-app: ~10,000 requests / 10 minutes
• Per-mailbox: ~10,000 requests / 10 minutes
• Throttled responses include Retry-After header