Skip to content

SharePoint Search & File Info

Search, list, and inspect SharePoint files (and OneDrive-for-Business documents) — including metadata, short-lived download URLs, and sharing permissions. File-level DTOs are reused as-is from the Drive surface; only the id prefix and the provider field differ.

GET/api/access/sharepoint/filesBearer Token

Search / List Files

Returns files in a folder/library, or a free-text search across the connected SharePoint surface when q is set.

Query Parameters

ParameterTypeDefaultDescription
qstring—Free-text query. Routed to Microsoft Graph search when present, otherwise a folder/library listing.
folderIdstring—Restrict to a single folder. Must be a sharepoint:drive:…:item:… ID.
mimeTypestring—Filter by MIME type.
limitint25Page size. Clamped to 1–100.
pageTokenstring—Opaque cursor returned on the previous page's nextPageToken.

Required Operation

Requires list_files or search_files — either is sufficient.

Common 422 Errors

Returns 422 Unprocessable Entity if SharePoint access is not enabled on the token (SHAREPOINT_NOT_ENABLED) or no SharePoint provider is connected (NO_SHAREPOINT_PROVIDER). See the SharePoint error reference.

Response 200 OK

{ 
  "files": [ 
    { 
      "id": "sharepoint:drive:b!…:item:01ABC…", 
      "name": "Q1 Plan.docx", 
      "mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document", 
      "size": 45821, 
      "createdTime": "2026-02-10T08:00:00Z", 
      "modifiedTime": "2026-04-21T14:21:00Z", 
      "owners": [{ "email": "jane@contoso.com", "displayName": "Jane Smith" }], 
      "webViewLink": "https://contoso.sharepoint.com/sites/marketing/Shared%20Documents/Q1%20Plan.docx", 
      "isFolder": false, 
      "provider": "SHAREPOINT" 
    } 
  ], 
  "nextPageToken": "eyJ0eXAiOi…", 
  "hasMore": true, 
  "accessInfo": null, 
  "authWarnings": [] 
}

Key Behaviors

  • Files blocked by SharePoint rules are silently excluded from results
  • Fields not in visibleSharePointFields are returned as null or omitted
  • accessInfo describes the token's restrictions in human-readable text — render it verbatim
  • authWarnings lists provider connections with OAuth refresh failures so a partial result set can still be surfaced — show as soft warnings, not errors
  • OneDrive-for-Business document libraries appear as ordinary SharePoint drives
GET/api/access/sharepoint/files/{fileId}Bearer Token

Get File Metadata

Returns metadata for a single file by its prefixed SharePoint file ID.

Required Operation

Requires get_file_metadata. URL-encode the : and , characters when embedding the ID in the path.

Response 200 OK

{ 
  "file": { 
    "id": "sharepoint:drive:b!…:item:01ABC…", 
    "name": "Q1 Plan.docx", 
    "mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document", 
    "size": 45821, 
    "createdTime": "2026-02-10T08:00:00Z", 
    "modifiedTime": "2026-04-21T14:21:00Z", 
    "owners": [{ "email": "jane@contoso.com", "displayName": "Jane Smith" }], 
    "webViewLink": "https://contoso.sharepoint.com/sites/…/Q1%20Plan.docx", 
    "isFolder": false, 
    "provider": "SHAREPOINT" 
  }, 
  "accessInfo": null 
}

Response 404 Not Found

{ 
  "file": null, 
  "accessInfo": "Access to this file is restricted." 
}

A 404 returned to the caller may be a real missing-resource or a policy-driven block. The accessInfo body distinguishes the two when populated.

Required Operation

Requires download_file.

Don't cache downloadUrl

The downloadUrl is Microsoft Graph's @microsoft.graph.downloadUrl — short-lived (~1 hour) and unauthenticated. Re-fetch on every download. Caching it client-side or in chat memory is a confidentiality footgun.

Response 200 OK

{ 
  "success": true, 
  "webViewLink": "https://contoso.sharepoint.com/sites/marketing/Shared%20Documents/Q1%20Plan.docx?web=1", 
  "downloadUrl": "https://contoso-my.sharepoint.com/personal/…/_layouts/…?download=1&…", 
  "exportLinks": null, 
  "fileName": "Q1 Plan.docx", 
  "mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document", 
  "size": 45821, 
  "isGoogleWorkspaceFile": false 
}

exportLinks and isGoogleWorkspaceFile are always null/false for SharePoint — the fields exist on the shared DTO so callers can route through a single code path with Drive responses.

Response 404 Not Found

{ 
  "error": "BLOCKED", 
  "message": "Access to this file is restricted by token policy." 
}
GET/api/access/sharepoint/files/{fileId}/permissionsBearer Token

Get File Permissions

Returns the sharing permissions (ACL) for a file.

Required Operation

Requires get_file_metadata.

Response 200 OK

{ 
  "permissions": [ 
    { 
      "id": "aTowIy5mfG1lbWJlcnNoaXB8…", 
      "type": "user", 
      "role": "owner", 
      "emailAddress": "jane@contoso.com", 
      "displayName": "Jane Smith" 
    }, 
    { 
      "id": "anonymous", 
      "type": "anyone", 
      "role": "reader" 
    } 
  ], 
  "accessInfo": null 
}

Permission Fields

FieldValues
typeuser, group, domain, anyone
roleowner, writer, reader (commenter is mapped to reader for SharePoint)