API
Drive
Files and folders in organizations and personal spaces: drives, uploads, versions, sharing, links, trash, search and ZIP downloads.
See Drive. Every route is under /v1/orgs/:orgId/drive (an organization's space) and /v1/me/drive (your personal space: signed-in people only, never keys). Public links are under /v1/hooks/drive without authentication.
Uploads: POST uploads answers the part size and links for the first parts; PUT each part's bytes to its link (any order, retried alone on failure), ask POST uploads/:uploadId/parts for more links, then POST uploads/:uploadId/complete. GET uploads/:uploadId lists the parts already stored, to resume.
Changes need drive:write as well as the access the item allows.
Every route below, with its parameters, request and response, errors and samples, is in the API reference.
| Route | What it does |
|---|---|
GET /v1/hooks/drive/links/:token | What a public link opens (name, type, size, photo details without location) or needsPassword. No authentication. 404 for links that were turned off, replaced, expired or trashed. |
POST /v1/hooks/drive/links/:token/unlock | Checks a link's password and answers a grant for 12 hours, sent as x-si-link-grant with the link's other calls. 10 wrong passwords per link lock it for 15 minutes. |
GET /v1/hooks/drive/links/:token/children | A folder's contents through its public link (folderId for folders inside it), with the path from the shared folder. |
GET /v1/hooks/drive/links/:token/file | A one-hour link to a file through its public link (itemId inside a shared folder; inline=1 to show it). Photos always come without location and camera details. |
POST /v1/hooks/drive/links/:token/archives | Starts a ZIP of the shared folder (or itemIds inside it); photos are cleaned of location details, and documents, spreadsheets and presentations go in as Word, Excel and PowerPoint. |
GET /v1/hooks/drive/links/:token/archives/:archiveId | A ZIP's status through its public link, with a download link when ready. |
POST /v1/hooks/drive/links/:token/exports | Starts a download of a document, spreadsheet or presentation in the link (fileId) as Word, Excel or PowerPoint, a job; the file's own pictures only. Counted per link and hour. |
GET /v1/hooks/drive/links/:token/jobs/:jobId | A download's status through its public link: when done, result.url (an hour) and result.left, what Word, Excel or PowerPoint changed or left out. |
GET /v1/orgs/:orgId/drive/drives | My Drive, the shared drives the caller belongs to (every one, to manage, for org admins) and storage use. |
POST /v1/orgs/:orgId/drive/drives | Creates a shared drive; the caller becomes its manager. Not in personal spaces; not for viewers. |
GET /v1/orgs/:orgId/drive/drives/:driveId | A drive with its members (shared drives) and whether the caller can manage them. |
PATCH /v1/orgs/:orgId/drive/drives/:driveId | Renames a shared drive or changes its description (managers, and org owners and admins). |
DELETE /v1/orgs/:orgId/drive/drives/:driveId | Deletes an empty shared drive (its trash too must be empty). |
PUT /v1/orgs/:orgId/drive/drives/:driveId/members/:principalId | Adds a person or team to a shared drive, or changes their role (viewer, commenter, editor, manager). A drive always keeps a manager who is a person. |
DELETE /v1/orgs/:orgId/drive/drives/:driveId/members/:principalId | Removes a member (anyone may remove themselves). |
GET /v1/orgs/:orgId/drive/usage | Storage the space uses (every version, the trash included) and its limit, in bytes. |
GET /v1/orgs/:orgId/drive/people | A person to share with, by exact email address: an org member here, any account for personal files. |
GET /v1/orgs/:orgId/drive/log | Personal spaces: the owner's log of every change and access (who opened, downloaded or listed what, links included). |
GET /v1/orgs/:orgId/drive/items/:itemId | A file or folder with its path (from the highest folder you can open), your role and what it allows, its shares (for editors) and its link setting. Photo details lose location and camera for people who only view, when the owner removes them. |
PATCH /v1/orgs/:orgId/drive/items/:itemId | Renames an item (names are unique per folder, ignoring case) or sets its description. Editors. |
GET /v1/orgs/:orgId/drive/items/:itemId/children | A folder's contents, folders first, sorted by name, modified or size (order), in pages of up to 1,000 (cursor). |
GET /v1/orgs/:orgId/drive/items/:itemId/file | A one-hour link to the file's bytes (inline=1 to show it in the browser; versionId for an earlier version, editors only; transcode=1 with inline=1: a video's preview transcode, pending while it's made). |
GET /v1/orgs/:orgId/drive/items/:itemId/versions | A file's versions, newest first, with who uploaded each; canManage for editors. |
POST /v1/orgs/:orgId/drive/items/:itemId/versions/:versionId/restore | Makes an earlier version current again as a new version (a copy in the bucket; counts against storage). Editors. |
DELETE /v1/orgs/:orgId/drive/items/:itemId/versions/:versionId | Deletes an earlier version (never the current one). Editors. |
GET /v1/orgs/:orgId/drive/items/:itemId/activity | What happened to an item (and, for folders, to what's in them), newest first, a year back. |
GET /v1/orgs/:orgId/drive/items/:itemId/comments | Comments on a file or folder, oldest first; canComment for commenters and editors. |
POST /v1/orgs/:orgId/drive/items/:itemId/comments | Adds a comment (up to 4,000 characters). Commenters and editors. |
DELETE /v1/orgs/:orgId/drive/items/:itemId/comments/:commentId | Deletes a comment: its author, or an editor. |
PUT /v1/orgs/:orgId/drive/items/:itemId/shares/:principalId | Shares an item (and everything in it) with a person or team as viewer, commenter or editor. Org spaces: members and teams of the org; personal spaces: any person, no teams. Editors; at most 100 per item. |
DELETE /v1/orgs/:orgId/drive/items/:itemId/shares/:principalId | Removes someone's access given on this item (inherited access stays). Anyone may remove their own. |
PUT /v1/orgs/:orgId/drive/items/:itemId/link | Link sharing and photo details: scope restricted, org or anyone; password null removes it; rotate makes a new link. |
POST /v1/orgs/:orgId/drive/items/:itemId/transfer | Gives a My Drive item (org spaces) to another member: it moves to the top of their My Drive and you keep editor access. Owners. |
POST /v1/orgs/:orgId/drive/folders | Creates a folder (onConflict: fail, the default, or rename for a numbered name). Editors of the parent. |
POST /v1/orgs/:orgId/drive/folders/paths | Folder uploads: makes each relative path's folders (a, a/b) under parentId, reusing existing ones. |
POST /v1/orgs/:orgId/drive/items/move | Moves items into a folder (up to 500). Between drives (everything inside goes too, at most 2,000 items) only for My Drive's owner or the source drive's managers. |
POST /v1/orgs/:orgId/drive/items/copy | Copies files (not folders) into a folder, Copy of … next to the original by default (server-side, up to 20 GB each; counts against storage). |
POST /v1/orgs/:orgId/drive/items/trash | Moves items (with everything in them) to their drive's trash; deleted forever after 30 days. Editors. |
POST /v1/orgs/:orgId/drive/items/restore | Puts trashed items back where they were (else at the top of their drive), with a numbered name if the name was taken meanwhile. |
POST /v1/orgs/:orgId/drive/items/delete | Deletes trashed items forever (owner or managers). Large folders finish in the background (done: false). |
POST /v1/orgs/:orgId/drive/items/star | Stars or unstars items for the caller (starred). |
GET /v1/orgs/:orgId/drive/trash | A drive's trash (My Drive by default, or driveId): items trashed there, newest first, with canEmpty for its owner or managers. |
POST /v1/orgs/:orgId/drive/trash/empty | Deletes everything in a drive's trash forever (My Drive by default). Owner or managers. |
GET /v1/orgs/:orgId/drive/recent | Files you opened or changed in the last 60 days, newest first. |
GET /v1/orgs/:orgId/drive/starred | Your starred items you can still open. |
GET /v1/orgs/:orgId/drive/shared | Items shared with you (or your teams), newest first, outside your own My Drive. Personal context: personal files people shared with you. |
GET /v1/orgs/:orgId/drive/search | Items you can open whose names contain every word of q, optionally by type, owner (me, others or a person's id), modifiedAfter/modifiedBefore (ms) or driveId. Up to 50,000 items are searched; truncated says when more weren't. |
POST /v1/orgs/:orgId/drive/uploads | Starts an upload: answers the part size and links for the first parts (PUT each part, then complete). |
POST /v1/orgs/:orgId/drive/uploads/:uploadId/parts | Links (an hour each) for more parts of an upload, up to 100 at a time. |
GET /v1/orgs/:orgId/drive/uploads/:uploadId | Where an upload stands, with the parts already stored, to resume it. |
POST /v1/orgs/:orgId/drive/uploads/:uploadId/complete | Finishes an upload once every part has arrived: checks the size, counts it against storage (413 when it doesn't fit) and records the file or its new version. |
DELETE /v1/orgs/:orgId/drive/uploads/:uploadId | Cancels an upload and discards its parts. |
POST /v1/orgs/:orgId/drive/archives | A ZIP of files and folders, made in the background; ask for it until status is ready, then download url. |
GET /v1/orgs/:orgId/drive/archives/:archiveId | A ZIP's status (queued, building, ready, failed) and, when ready, a one-hour download link; left adds up what its Word, Excel and PowerPoint files changed or left out. |
GET /v1/me/drive/drives | My Drive, the shared drives the caller belongs to (every one, to manage, for org admins) and storage use. |
POST /v1/me/drive/drives | Creates a shared drive; the caller becomes its manager. Not in personal spaces; not for viewers. |
GET /v1/me/drive/drives/:driveId | A drive with its members (shared drives) and whether the caller can manage them. |
PATCH /v1/me/drive/drives/:driveId | Renames a shared drive or changes its description (managers, and org owners and admins). |
DELETE /v1/me/drive/drives/:driveId | Deletes an empty shared drive (its trash too must be empty). |
PUT /v1/me/drive/drives/:driveId/members/:principalId | Adds a person or team to a shared drive, or changes their role (viewer, commenter, editor, manager). A drive always keeps a manager who is a person. |
DELETE /v1/me/drive/drives/:driveId/members/:principalId | Removes a member (anyone may remove themselves). |
GET /v1/me/drive/usage | Storage the space uses (every version, the trash included) and its limit, in bytes. |
GET /v1/me/drive/people | A person to share with, by exact email address: an org member here, any account for personal files. |
GET /v1/me/drive/log | Personal spaces: the owner's log of every change and access (who opened, downloaded or listed what, links included). |
GET /v1/me/drive/items/:itemId | A file or folder with its path (from the highest folder you can open), your role and what it allows, its shares (for editors) and its link setting. Photo details lose location and camera for people who only view, when the owner removes them. |
PATCH /v1/me/drive/items/:itemId | Renames an item (names are unique per folder, ignoring case) or sets its description. Editors. |
GET /v1/me/drive/items/:itemId/children | A folder's contents, folders first, sorted by name, modified or size (order), in pages of up to 1,000 (cursor). |
GET /v1/me/drive/items/:itemId/file | A one-hour link to the file's bytes (inline=1 to show it in the browser; versionId for an earlier version, editors only; transcode=1 with inline=1: a video's preview transcode, pending while it's made). |
GET /v1/me/drive/items/:itemId/versions | A file's versions, newest first, with who uploaded each; canManage for editors. |
POST /v1/me/drive/items/:itemId/versions/:versionId/restore | Makes an earlier version current again as a new version (a copy in the bucket; counts against storage). Editors. |
DELETE /v1/me/drive/items/:itemId/versions/:versionId | Deletes an earlier version (never the current one). Editors. |
GET /v1/me/drive/items/:itemId/activity | What happened to an item (and, for folders, to what's in them), newest first, a year back. |
GET /v1/me/drive/items/:itemId/comments | Comments on a file or folder, oldest first; canComment for commenters and editors. |
POST /v1/me/drive/items/:itemId/comments | Adds a comment (up to 4,000 characters). Commenters and editors. |
DELETE /v1/me/drive/items/:itemId/comments/:commentId | Deletes a comment: its author, or an editor. |
PUT /v1/me/drive/items/:itemId/shares/:principalId | Shares an item (and everything in it) with a person or team as viewer, commenter or editor. Org spaces: members and teams of the org; personal spaces: any person, no teams. Editors; at most 100 per item. |
DELETE /v1/me/drive/items/:itemId/shares/:principalId | Removes someone's access given on this item (inherited access stays). Anyone may remove their own. |
PUT /v1/me/drive/items/:itemId/link | Link sharing and photo details: scope restricted, org or anyone; password null removes it; rotate makes a new link. |
POST /v1/me/drive/items/:itemId/transfer | Gives a My Drive item (org spaces) to another member: it moves to the top of their My Drive and you keep editor access. Owners. |
POST /v1/me/drive/folders | Creates a folder (onConflict: fail, the default, or rename for a numbered name). Editors of the parent. |
POST /v1/me/drive/folders/paths | Folder uploads: makes each relative path's folders (a, a/b) under parentId, reusing existing ones. |
POST /v1/me/drive/items/move | Moves items into a folder (up to 500). Between drives (everything inside goes too, at most 2,000 items) only for My Drive's owner or the source drive's managers. |
POST /v1/me/drive/items/copy | Copies files (not folders) into a folder, Copy of … next to the original by default (server-side, up to 20 GB each; counts against storage). |
POST /v1/me/drive/items/trash | Moves items (with everything in them) to their drive's trash; deleted forever after 30 days. Editors. |
POST /v1/me/drive/items/restore | Puts trashed items back where they were (else at the top of their drive), with a numbered name if the name was taken meanwhile. |
POST /v1/me/drive/items/delete | Deletes trashed items forever (owner or managers). Large folders finish in the background (done: false). |
POST /v1/me/drive/items/star | Stars or unstars items for the caller (starred). |
GET /v1/me/drive/trash | A drive's trash (My Drive by default, or driveId): items trashed there, newest first, with canEmpty for its owner or managers. |
POST /v1/me/drive/trash/empty | Deletes everything in a drive's trash forever (My Drive by default). Owner or managers. |
GET /v1/me/drive/recent | Files you opened or changed in the last 60 days, newest first. |
GET /v1/me/drive/starred | Your starred items you can still open. |
GET /v1/me/drive/shared | Items shared with you (or your teams), newest first, outside your own My Drive. Personal context: personal files people shared with you. |
GET /v1/me/drive/search | Items you can open whose names contain every word of q, optionally by type, owner (me, others or a person's id), modifiedAfter/modifiedBefore (ms) or driveId. Up to 50,000 items are searched; truncated says when more weren't. |
POST /v1/me/drive/uploads | Starts an upload: answers the part size and links for the first parts (PUT each part, then complete). |
POST /v1/me/drive/uploads/:uploadId/parts | Links (an hour each) for more parts of an upload, up to 100 at a time. |
GET /v1/me/drive/uploads/:uploadId | Where an upload stands, with the parts already stored, to resume it. |
POST /v1/me/drive/uploads/:uploadId/complete | Finishes an upload once every part has arrived: checks the size, counts it against storage (413 when it doesn't fit) and records the file or its new version. |
DELETE /v1/me/drive/uploads/:uploadId | Cancels an upload and discards its parts. |
POST /v1/me/drive/archives | A ZIP of files and folders, made in the background; ask for it until status is ready, then download url. |
GET /v1/me/drive/archives/:archiveId | A ZIP's status (queued, building, ready, failed) and, when ready, a one-hour download link; left adds up what its Word, Excel and PowerPoint files changed or left out. |