Files

For a list of methods for this resource, see the end of this page.

Resource representations

The metadata for a file.

{
  "kind": "drive#file",
  "id": string,
  "etag": etag,
  "selfLink": string,
  "webContentLink": string,
  "webViewLink": string,
  "alternateLink": string,
  "embedLink": string,
  "openWithLinks": {
    (key): string
  },
  "defaultOpenWithLink": string,
  "iconLink": string,
  "hasThumbnail": boolean,
  "thumbnailLink": string,
  "thumbnailVersion": long,
  "thumbnail": {
    "image": bytes,
    "mimeType": string
  },
  "title": string,
  "mimeType": string,
  "description": string,
  "labels": {
    "starred": boolean,
    "hidden": boolean,
    "trashed": boolean,
    "restricted": boolean,
    "viewed": boolean,
    "modified": boolean
  },
  "createdDate": datetime,
  "modifiedDate": datetime,
  "modifiedByMeDate": datetime,
  "lastViewedByMeDate": datetime,
  "markedViewedByMeDate": datetime,
  "sharedWithMeDate": datetime,
  "version": long,
  "sharingUser": {
    "kind": "drive#user",
    "displayName": string,
    "picture": {
      "url": string
    },
    "isAuthenticatedUser": boolean,
    "permissionId": string,
    "emailAddress": string
  },
  "parents": [
    parents Resource
  ],
  "downloadUrl": string,
  "downloadUrl": string,
  "exportLinks": {
    (key): string
  },
  "indexableText": {
    "text": string
  },
  "userPermission": permissions Resource,
  "permissions": [
    permissions Resource
  ],
  "hasAugmentedPermissions": boolean,
  "originalFilename": string,
  "fileExtension": string,
  "fullFileExtension": string,
  "md5Checksum": string,
  "fileSize": long,
  "quotaBytesUsed": long,
  "ownerNames": [
    string
  ],
  "owners": [
    {
      "kind": "drive#user",
      "displayName": string,
      "picture": {
        "url": string
      },
      "isAuthenticatedUser": boolean,
      "permissionId": string,
      "emailAddress": string
    }
  ],
  "teamDriveId": string,
  "lastModifyingUserName": string,
  "lastModifyingUser": {
    "kind": "drive#user",
    "displayName": string,
    "picture": {
      "url": string
    },
    "isAuthenticatedUser": boolean,
    "permissionId": string,
    "emailAddress": string
  },
  "ownedByMe": boolean,
  "capabilities": {
    "canAddChildren": boolean,
    "canChangeRestrictedDownload": boolean,
    "canComment": boolean,
    "canCopy": boolean,
    "canDelete": boolean,
    "canDownload": boolean,
    "canEdit": boolean,
    "canListChildren": boolean,
    "canMoveItemIntoTeamDrive": boolean,
    "canMoveTeamDriveItem": boolean,
    "canReadRevisions": boolean,
    "canReadTeamDrive": boolean,
    "canRemoveChildren": boolean,
    "canRename": boolean,
    "canShare": boolean,
    "canTrash": boolean,
    "canUntrash": boolean
  },
  "editable": boolean,
  "canComment": boolean,
  "canReadRevisions": boolean,
  "shareable": boolean,
  "copyable": boolean,
  "writersCanShare": boolean,
  "shared": boolean,
  "explicitlyTrashed": boolean,
  "trashingUser": {
    "kind": "drive#user",
    "displayName": string,
    "picture": {
      "url": string
    },
    "isAuthenticatedUser": boolean,
    "permissionId": string,
    "emailAddress": string
  },
  "trashedDate": datetime,
  "appDataContents": boolean,
  "headRevisionId": string,
  "properties": [
    properties Resource
  ],
  "folderColorRgb": string,
  "imageMediaMetadata": {
    "width": integer,
    "height": integer,
    "rotation": integer,
    "location": {
      "latitude": double,
      "longitude": double,
      "altitude": double
    },
    "date": string,
    "cameraMake": string,
    "cameraModel": string,
    "exposureTime": float,
    "aperture": float,
    "flashUsed": boolean,
    "focalLength": float,
    "isoSpeed": integer,
    "meteringMode": string,
    "sensor": string,
    "exposureMode": string,
    "colorSpace": string,
    "whiteBalance": string,
    "exposureBias": float,
    "maxApertureValue": float,
    "subjectDistance": integer,
    "lens": string
  },
  "videoMediaMetadata": {
    "width": integer,
    "height": integer,
    "durationMillis": long
  },
  "spaces": [
    string
  ],
  "isAppAuthorized": boolean
}
Property name Value Description Notes
kind string The type of file. This is always drive#file.
id string The ID of the file. writable
etag etag ETag of the file.
title string The title of this file. Note that for immutable items such as the top level folders of Team Drives, My Drive root folder, and Application Data folder the title is constant. writable
mimeType string The MIME type of the file. This is only mutable on update when uploading new content. This field can be left blank, and the mimetype will be determined from the uploaded content's MIME type. writable
description string A short description of the file. writable
labels object A group of labels for the file.
labels.starred boolean Whether this file is starred by the user. writable
labels.hidden boolean Deprecated. writable
labels.trashed boolean Whether this file has been trashed. This label applies to all users accessing the file; however, only owners are allowed to see and untrash files. writable
createdDate datetime Create time for this file (formatted RFC 3339 timestamp).
modifiedDate datetime Last time this file was modified by anyone (formatted RFC 3339 timestamp). This is only mutable on update when the setModifiedDate parameter is set. writable
modifiedByMeDate datetime Last time this file was modified by the user (formatted RFC 3339 timestamp). Note that setting modifiedDate will also update the modifiedByMe date for the user which set the date.
downloadUrl string
indexableText object Indexable text attributes for the file. This property can only be written, and is not returned by files.get. For more information, see Custom thumbnails and indexable text.
indexableText.text string The text to be indexed for this file. writable
userPermission nested object The permissions for the authenticated user on this file.
fileExtension string The final component of fullFileExtension with trailing text that does not appear to be part of the extension removed. This field is only populated for files with content stored in Drive; it is not populated for Google Docs or shortcut files.
md5Checksum string An MD5 checksum for the content of this file. This field is only populated for files with content stored in Drive; it is not populated for Google Docs or shortcut files.
fileSize long The size of the file in bytes. This field is only populated for files with content stored in Drive; it is not populated for Google Docs or shortcut files.
labels.restricted boolean Whether viewers and commenters are prevented from downloading, printing, and copying this file. writable
labels.viewed boolean Whether this file has been viewed by this user. writable
sharedWithMeDate datetime Time at which this file was shared with the user (formatted RFC 3339 timestamp).
parents[] list Collection of parent folders which contain this file.

Setting this field will put the file in all of the provided folders. On insert, if no folders are provided, the file will be placed in the default root folder.

writable
exportLinks.(key) string A mapping from export format to URL
originalFilename string The original filename of the uploaded content if available, or else the original value of the title field. This is only available for files with binary content in Drive. writable
quotaBytesUsed long The number of quota bytes used by this file.
ownerNames[] list Name(s) of the owner(s) of this file. Not populated for Team Drive files.
lastModifyingUserName string Name of the last user to modify this file.
editable boolean Deprecated: use capabilities/canEdit.
writersCanShare boolean Whether writers can share the document with other users. Not populated for Team Drive files. writable
lastViewedByMeDate datetime Last time this file was viewed by the user (formatted RFC 3339 timestamp). writable
explicitlyTrashed boolean Whether this file has been explicitly trashed, as opposed to recursively trashed.
imageMediaMetadata object Metadata about image media. This will only be present for image types, and its contents will depend on what can be parsed from the image content.
imageMediaMetadata.width integer The width of the image in pixels.
imageMediaMetadata.height integer The height of the image in pixels.
imageMediaMetadata.rotation integer The rotation in clockwise degrees from the image's original orientation.
imageMediaMetadata.location object Geographic location information stored in the image.
imageMediaMetadata.location.latitude double The latitude stored in the image.
imageMediaMetadata.location.longitude double The longitude stored in the image.
imageMediaMetadata.location.altitude double The altitude stored in the image.
thumbnail object A thumbnail for the file. This will only be used if Drive cannot generate a standard thumbnail.
thumbnail.image bytes The URL-safe Base64 encoded bytes of the thumbnail image. It should conform to RFC 4648 section 5.
thumbnail.mimeType string The MIME type of the thumbnail.
imageMediaMetadata.date string The date and time the photo was taken (EXIF format timestamp).
imageMediaMetadata.cameraMake string The make of the camera used to create the photo.
imageMediaMetadata.cameraModel string The model of the camera used to create the photo.
imageMediaMetadata.exposureTime float The length of the exposure, in seconds.
imageMediaMetadata.aperture float The aperture used to create the photo (f-number).
imageMediaMetadata.flashUsed boolean Whether a flash was used to create the photo.
imageMediaMetadata.focalLength float The focal length used to create the photo, in millimeters.
imageMediaMetadata.isoSpeed integer The ISO speed used to create the photo.
imageMediaMetadata.meteringMode string The metering mode used to create the photo.
imageMediaMetadata.sensor string The type of sensor used to create the photo.
imageMediaMetadata.exposureMode string The exposure mode used to create the photo.
imageMediaMetadata.colorSpace string The color space of the photo.
imageMediaMetadata.whiteBalance string The white balance mode used to create the photo.
imageMediaMetadata.exposureBias float The exposure bias of the photo (APEX value).
imageMediaMetadata.maxApertureValue float The smallest f-number of the lens at the focal length used to create the photo (APEX value).
imageMediaMetadata.subjectDistance integer The distance to the subject of the photo, in meters.
imageMediaMetadata.lens string The lens used to create the photo.
shared boolean Whether the file has been shared. Not populated for Team Drive files.
owners[] list The owner(s) of this file. Not populated for Team Drive files.
owners[].kind string This is always drive#user.
owners[].displayName string A plain text displayable name for this user.
owners[].picture object The user's profile picture.
owners[].picture.url string A URL that points to a profile picture of this user.
owners[].isAuthenticatedUser boolean Whether this user is the same as the authenticated user for whom the request was made.
owners[].permissionId string The user's ID as visible in the permissions collection.
lastModifyingUser nested object The last user to modify this file.
lastModifyingUser.kind string This is always drive#user.
lastModifyingUser.displayName string A plain text displayable name for this user.
lastModifyingUser.picture object The user's profile picture.
lastModifyingUser.picture.url string A URL that points to a profile picture of this user.
lastModifyingUser.isAuthenticatedUser boolean Whether this user is the same as the authenticated user for whom the request was made.
lastModifyingUser.permissionId string The user's ID as visible in the permissions collection.
appDataContents boolean Whether this file is in the Application Data folder.
openWithLinks.(key) string
headRevisionId string The ID of the file's head revision. This field is only populated for files with content stored in Drive; it is not populated for Google Docs or shortcut files.
copyable boolean Deprecated: use capabilities/canCopy.
properties[] list The list of properties. writable
owners[].emailAddress string The email address of the user.
lastModifyingUser.emailAddress string The email address of the user. This field is returned only if the last modifying user is an owner of the file, the requesting user is an owner or can modify the file, or if the last modifying user's email address is visible.
markedViewedByMeDate datetime Deprecated. writable
version long A monotonically increasing version number for the file. This reflects every change made to the file on the server, even those not visible to the requesting user.
sharingUser nested object User that shared the item with the current user, if available.
sharingUser.kind string This is always drive#user.
sharingUser.displayName string A plain text displayable name for this user.
sharingUser.picture object The user's profile picture.
sharingUser.picture.url string A URL that points to a profile picture of this user.
sharingUser.isAuthenticatedUser boolean Whether this user is the same as the authenticated user for whom the request was made.
sharingUser.permissionId string The user's ID as visible in the permissions collection.
sharingUser.emailAddress string The email address of the user.
permissions[] list The list of permissions for users with access to this file. Not populated for Team Drive files.
videoMediaMetadata object Metadata about video media. This will only be present for video types.
videoMediaMetadata.width integer The width of the video in pixels.
videoMediaMetadata.height integer The height of the video in pixels.
videoMediaMetadata.durationMillis long The duration of the video in milliseconds.
folderColorRgb string Folder color as an RGB hex string if the file is a folder. The list of supported colors is available in the folderColorPalette field of the About resource. If an unsupported color is specified, it will be changed to the closest color in the palette. Not populated for Team Drive files. writable
fullFileExtension string The full file extension; extracted from the title. May contain multiple concatenated extensions, such as "tar.gz". Removing an extension from the title does not clear this field; however, changing the extension on the title does update this field. This field is only populated for files with content stored in Drive; it is not populated for Google Docs or shortcut files.
ownedByMe boolean Whether the file is owned by the current user. Not populated for Team Drive files.
canComment boolean Deprecated: use capabilities/canComment.
shareable boolean Deprecated: use capabilities/canShare.
spaces[] list The list of spaces which contain the file. Supported values are 'drive', 'appDataFolder' and 'photos'.
canReadRevisions boolean Deprecated: use capabilities/canReadRevisions.
isAppAuthorized boolean Whether the file was created or opened by the requesting app.
hasThumbnail boolean Whether this file has a thumbnail. This does not indicate whether the requesting app has access to the thumbnail. To check access, look for the presence of the thumbnailLink field.
thumbnailVersion long The thumbnail version for use in thumbnail cache invalidation.
labels.modified boolean Whether the file has been modified by this user.
hasAugmentedPermissions boolean Whether any users are granted file access directly on this file. This field is only populated for Team Drive files.
teamDriveId string ID of the Team Drive the file resides in.
capabilities object Capabilities the current user has on this file. Each capability corresponds to a fine-grained action that a user may take.
capabilities.canAddChildren boolean Whether the current user can add children to this folder. This is always false when the item is not a folder.
capabilities.canComment boolean Whether the current user can comment on this file.
capabilities.canCopy boolean Whether the current user can copy this file. For a Team Drive item, whether the current user can copy non-folder descendants of this item, or this item itself if it is not a folder.
capabilities.canDelete boolean Whether the current user can delete this file.
capabilities.canDownload boolean Whether the current user can download this file.
capabilities.canEdit boolean Whether the current user can edit this file.
capabilities.canListChildren boolean Whether the current user can list the children of this folder. This is always false when the item is not a folder.
capabilities.canMoveItemIntoTeamDrive boolean Whether the current user can move this item into a Team Drive. If the item is in a Team Drive, this field is equivalent to canMoveTeamDriveItem.
capabilities.canMoveTeamDriveItem boolean Whether the current user can move this Team Drive item by changing its parent. Note that a request to change the parent for this item may still fail depending on the new parent that is being added. Only populated for Team Drive files.
capabilities.canReadRevisions boolean Whether the current user can read the revisions resource of this file. For a Team Drive item, whether revisions of non-folder descendants of this item, or this item itself if it is not a folder, can be read.
capabilities.canReadTeamDrive boolean Whether the current user can read the Team Drive to which this file belongs. Only populated for Team Drive files.
capabilities.canRemoveChildren boolean Whether the current user can remove children from this folder. This is always false when the item is not a folder.
capabilities.canRename boolean Whether the current user can rename this file.
capabilities.canShare boolean Whether the current user can modify the sharing settings for this file.
capabilities.canTrash boolean Whether the current user can move this file to trash.
capabilities.canUntrash boolean Whether the current user can restore this file from trash.
trashingUser nested object If the file has been explicitly trashed, the user who trashed it. Only populated for Team Drive files.
trashingUser.kind string This is always drive#user.
trashingUser.displayName string A plain text displayable name for this user.
trashingUser.picture object The user's profile picture.
trashingUser.picture.url string A URL that points to a profile picture of this user.
trashingUser.isAuthenticatedUser boolean Whether this user is the same as the authenticated user for whom the request was made.
trashingUser.permissionId string The user's ID as visible in the permissions collection.
trashingUser.emailAddress string The email address of the user.
trashedDate datetime The time that the item was trashed (formatted RFC 3339 timestamp). Only populated for Team Drive files.
capabilities.canChangeRestrictedDownload boolean Whether the current user can change the restricted download label of this file.

Methods

get
Gets a file's metadata by ID.
insert
Insert a new file.
patch
Updates file metadata. This method supports patch semantics.
update
Updates file metadata and/or content.
copy
Creates a copy of the specified file.
delete
Permanently deletes a file by ID. Skips the trash. The currently authenticated user must own the file or be an organizer on the parent for Team Drive files.
list
Lists the user's files.
touch
Set the file's updated time to the current server time.
trash
Moves a file to the trash. The currently authenticated user must own the file or be an organizer on the parent for Team Drive files.
untrash
Restores a file from the trash.
watch
Start watching for changes to a file.
emptyTrash
Permanently deletes all of the user's trashed files.
generateIds
Generates a set of file IDs which can be provided in insert requests.
export
Exports a Google Doc to the requested MIME type and returns the exported content.

Send feedback about...

Drive REST API v2
Drive REST API v2