Search & File Info

Search, list, and inspect Google Drive files — including metadata, download/export links, and sharing permissions.

GET/api/access/drive/filesBearer Token

Search / List Files

Returns files matching optional search, folder, MIME type, and date filters with pagination.

Query Parameters

Parameter	Type	Default	Description
q	string	—	Free-text search (file names and content)
folderId	string	—	Restrict to files in a specific folder (provider-prefixed ID)
mimeType	string	—	Filter by MIME type (e.g., application/pdf)
name	string	—	Filter by file name (partial match)
trashedOnly	bool	false	Only return trashed files
sharedWithMe	bool	—	Only return files shared with the connected user
modifiedAfter	datetime	—	Files modified after this ISO 8601 date
modifiedBefore	datetime	—	Files modified before this ISO 8601 date
limit	int	25	Results per page (1–100)
pageToken	string	—	Pagination cursor from previous response's nextPageToken
orderBy	string	modified_time	Sort: name, modified_time, created_time, size

Required Operation

Requires list_files or search_files permission. Use q for full-text search or omit it to list folder contents.

Common 422 Errors

All drive endpoints can return 422 Unprocessable Entity if drive access is not enabled on the token (DRIVE_NOT_ENABLED) or no drive provider is connected (NO_DRIVE_PROVIDER). See the error handling page for details.

Response 200 OK

{ 
  "files": [ 
    { 
      "id": "google:1BxiMVs0XRA5nkz...", 
      "name": "Q1 Budget Report.pdf", 
      "mimeType": "application/pdf", 
      "size": 245760, 
      "createdTime": "2026-01-15T09:00:00Z", 
      "modifiedTime": "2026-03-01T14:30:00Z", 
      "owners": [ 
        { "email": "john@example.com", "displayName": "John Doe", "role": "owner" } 
      ], 
      "sharedWith": [ 
        { "email": "jane@example.com", "displayName": "Jane Smith", "role": "writer" } 
      ], 
      "description": "Quarterly budget report", 
      "webViewLink": "https://docs.google.com/document/d/1BxiMVs0XRA5.../edit", 
      "parentFolderId": "google:0B7_FINANCE_FOLDER", 
      "parentFolderName": "Finance", 
      "isFolder": false, 
      "downloadLink": "https://www.googleapis.com/drive/v3/files/1BxiMVs0XRA5nkz...?alt=media", 
      "labels": { "status": "approved" }, 
      "provider": "GOOGLE" 
    } 
  ], 
  "nextPageToken": "eyJ0eXAi...", 
  "hasMore": true, 
  "accessInfo": "Read-only drive access, cannot upload, create, rename, move, delete, or share files. Drive is in block-all mode: only files matching allow rules are accessible. The user can adjust these permissions at https://my.porteden.com", 
  "authWarnings": [] 
}

Key Behaviors

Files blocked by drive rules are silently excluded from results
Fields not in visibleDriveFields are returned as null
accessInfo describes the token's restrictions in human-readable text (useful for AI agents)
authWarnings lists provider connections that failed to authenticate — results from working connections are still returned
Results are aggregated across all connected drive providers

File Object Fields

Field	Type	Description
id	string	Provider-prefixed file ID
name	string	File name
mimeType	string	MIME content type
size	long?	File size in bytes (null for Google Workspace files)
createdTime	DateTime?	When the file was created
modifiedTime	DateTime?	When the file was last modified
owners	FileUser[]?	File owners
sharedWith	FileUser[]?	Users the file is shared with
description	string?	File description
webViewLink	string?	URL to view the file in a browser
parentFolderId	string?	Provider-prefixed parent folder ID
parentFolderName	string?	Parent folder name
isFolder	bool	Whether this is a folder
downloadLink	string?	Direct download URL (non-Workspace files only)
labels	object?	Dictionary of label key-value pairs on the file
provider	string	Source provider: GOOGLE

GET/api/access/drive/files/{fileId}Bearer Token

Get File Metadata

Returns metadata for a single file by its provider-prefixed ID.

Required Operation

Requires get_file_metadata permission. The fileId must be provider-prefixed (e.g., google:1BxiMVs0XRA5...).

Response 200 OK

{ 
  "file": { 
    "id": "google:1BxiMVs0XRA5...", 
    "name": "Project Brief.docx", 
    "mimeType": "application/vnd.google-apps.document", 
    "size": 45056, 
    "createdTime": "2026-02-10T08:00:00Z", 
    "modifiedTime": "2026-03-05T16:20:00Z", 
    "owners": [{ "email": "jane@example.com", "displayName": "Jane Smith", "role": "owner" }], 
    "isFolder": false, 
    "provider": "GOOGLE" 
  }, 
  "accessInfo": null 
}

Response 404 Not Found

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

Response 400 Bad Request

{ 
  "error": "INVALID_FILE_ID", 
  "message": "Invalid file ID." 
}

GET/api/access/drive/files/{fileId}/downloadBearer Token

Get File Links

Returns links for viewing, downloading, or exporting a file. No binary content is streamed — the response is always JSON containing URLs.

Required Operation

Requires download_file permission.

Google Workspace File (e.g., Google Docs)

Response 200 OK

{ 
  "success": true, 
  "webViewLink": "https://docs.google.com/document/d/1BxiMVs0XRA5.../edit", 
  "downloadUrl": null, 
  "exportLinks": { 
    "pdf": "https://docs.google.com/document/d/1BxiMVs0XRA5.../export?format=pdf", 
    "docx": "https://docs.google.com/document/d/1BxiMVs0XRA5.../export?format=docx", 
    "txt": "https://docs.google.com/document/d/1BxiMVs0XRA5.../export?format=txt" 
  }, 
  "fileName": "Project Brief", 
  "mimeType": "application/vnd.google-apps.document", 
  "size": null, 
  "isGoogleWorkspaceFile": true, 
  "errorMessage": null, 
  "errorCode": null 
}

Regular File (e.g., PDF)

Response 200 OK

{ 
  "success": true, 
  "webViewLink": "https://drive.google.com/file/d/1ABC.../view", 
  "downloadUrl": "https://www.googleapis.com/drive/v3/files/1ABC...?alt=media", 
  "exportLinks": null, 
  "fileName": "report.pdf", 
  "mimeType": "application/pdf", 
  "size": 245760, 
  "isGoogleWorkspaceFile": false, 
  "errorMessage": null, 
  "errorCode": null 
}

Google Workspace Export Formats

File Type	Available Formats
Google Docs	pdf, docx, txt
Google Sheets	xlsx, pdf, csv
Google Slides	pdf, pptx
Google Drawings	png, svg, pdf

Response 400 Bad Request

{ 
  "error": "INVALID_FILE_ID", 
  "message": "Invalid file ID." 
}

GET/api/access/drive/files/{fileId}/permissionsBearer Token

Get File Permissions

Returns the sharing permissions (ACL) for a file.

Required Operation

Requires get_file_metadata permission.

Response 200 OK

{ 
  "permissions": [ 
    { 
      "id": "12345", 
      "type": "user", 
      "role": "owner", 
      "emailAddress": "jane@example.com", 
      "displayName": "Jane Smith" 
    }, 
    { 
      "id": "67890", 
      "type": "anyone", 
      "role": "reader", 
      "emailAddress": null, 
      "domain": null, 
      "displayName": null 
    } 
  ], 
  "accessInfo": null 
}

Permission Fields

Field	Values
type	user, group, domain, anyone
role	owner, writer, reader, commenter

Response 400 Bad Request

{ 
  "error": "INVALID_FILE_ID", 
  "message": "Invalid file ID." 
}