API
Documents, Sheets and Slides
Creating and co-editing documents, spreadsheets and presentations, their versions, comments, templates, imports, downloads and search.
See Documents, Sheets and Slides. Every route is under /v1/orgs/:orgId/office (an organization's files) and /v1/me/office (your personal space: signed-in people only, never keys). Public links and the print page's render tokens are under /v1/hooks/office without a session.
The files are Drive files: move, share, star, trash and delete them with Drive's API, which decides every access check here too. Reading needs drive:read; changes need drive:write as well as the access the file allows.
Editing: GET files/:fileId/collab answers the file's state (base64 Yjs: the latest version plus the edits after it), its epoch and seq, your rights, and a ticket for the co-editing socket. Edits go over the socket, or to POST files/:fileId/collab/updates when they're larger than 90 KB. When an answer says reset, the file was replaced (a restore or an upload): load the state again.
Imports and downloads in other formats are jobs: POST imports or POST exports answers a job; ask GET jobs/:jobId until it's done (a new file, or a download link good for a day) or failed.
Every route below, with its parameters, request and response, errors and samples, is in the API reference.
| Route | What it does |
|---|---|
GET /v1/hooks/office/links/:token/state | A document, spreadsheet or presentation through its public link, for viewing: its name, kind and state (base64 Yjs). No authentication; password-protected links need their grant (x-si-link-grant). |
GET /v1/hooks/office/links/:token/media/:mediaId | A picture in a file shared by a public link. |
GET /v1/hooks/office/render/:token/state | The file a render token names (a two-minute token for printing and PDF downloads), for the print page. |
GET /v1/hooks/office/render/:token/media/:mediaId | A picture in the file a render token names. |
POST /v1/orgs/:orgId/office/files | A new document, spreadsheet or presentation (blank, a built-in template or one of the org's), in parentId or My Drive. |
GET /v1/orgs/:orgId/office/files/:fileId | A document, spreadsheet or presentation: its Drive item, kind, what you may do (rights: edit, comment, share) and where it is. |
POST /v1/orgs/:orgId/office/files/:fileId/copy | Makes a copy ("Copy of …", or name) in parentId or beside it, with its pictures; versionId copies an earlier version. |
GET /v1/orgs/:orgId/office/files/:fileId/collab | The shared document with the caller's rights and a socket ticket (ticket=0 without; state=0 for a ticket alone, on reconnects). |
POST /v1/orgs/:orgId/office/files/:fileId/collab/seed | Sets up a file nobody has edited yet: the first update (base64 Yjs) on the version base. 409 when it's already set up. |
POST /v1/orgs/:orgId/office/files/:fileId/collab/updates | Sends an edit (update, base64 Yjs) at epoch; answers its seq. For edits too large for the socket (over 90 KB). 409 when the epoch is stale: reload the state. |
GET /v1/orgs/:orgId/office/files/:fileId/collab/updates | Edits after after at epoch, or { reset: true } when the file was replaced since (a restore or an upload): reload the state. |
POST /v1/orgs/:orgId/office/files/:fileId/checkpoint | Saves a checkpoint now (a Drive version): on leaving, every 10 minutes of editing, or named. |
POST /v1/orgs/:orgId/office/files/:fileId/media | A picture into the file: a one-part upload link, then …/complete; GET a one-hour link to it. |
POST /v1/orgs/:orgId/office/files/:fileId/media/:mediaId/complete | Finishes a picture's upload (after the PUT to the link POST …/media answered). |
GET /v1/orgs/:orgId/office/files/:fileId/media/:mediaId | A short-lived link to a picture in the file. |
GET /v1/orgs/:orgId/office/files/:fileId/versions | Versions (Drive's, newest first) with names and pins, whether you may manage them, and how many changes aren't in a version yet (unsaved). |
GET /v1/orgs/:orgId/office/files/:fileId/versions/:versionId/content | An earlier version's state (base64 Yjs) for viewing. Editors only, as in Drive. |
PATCH /v1/orgs/:orgId/office/files/:fileId/versions/:versionId | Names (name, null to clear) or pins (pinned) a version. Pinned versions aren't pruned. |
POST /v1/orgs/:orgId/office/files/:fileId/versions/:versionId/restore | Makes an earlier version current again (a new version with its content); open editors reload. |
GET /v1/orgs/:orgId/office/files/:fileId/threads | Comment threads on the file, with their anchors (text, cell, slide element or point) and authors' names. |
POST /v1/orgs/:orgId/office/files/:fileId/threads | Starts a thread at anchor with body (Markdown; @[Name](usr_…) mentions notify). Commenters and up. |
POST /v1/orgs/:orgId/office/files/:fileId/threads/:threadId/comments | Replies to a thread (and reopens it if it was resolved). |
PATCH /v1/orgs/:orgId/office/files/:fileId/threads/:threadId | Resolves or reopens a thread (resolved). Anyone who can comment. |
DELETE /v1/orgs/:orgId/office/files/:fileId/threads/:threadId | Deletes a thread. Its author, or an editor of the file. |
PATCH /v1/orgs/:orgId/office/files/:fileId/threads/:threadId/comments/:commentId | Edits your own comment (body). |
DELETE /v1/orgs/:orgId/office/files/:fileId/threads/:threadId/comments/:commentId | Deletes a comment: your own, or any as an editor of the file. |
POST /v1/orgs/:orgId/office/files/:fileId/mentions | People @mentioned who can't open the file yet (the commenter is asked to share first). |
GET /v1/orgs/:orgId/office/files/:fileId/lock | Editing locks (Studio: one editor at a time; renew every minute). |
POST /v1/orgs/:orgId/office/files/:fileId/lock | Takes or renews the editing lock for one-at-a-time editing (renew every minute). 423 with who has it when someone else does. |
DELETE /v1/orgs/:orgId/office/files/:fileId/lock | Gives up the editing lock. |
GET /v1/orgs/:orgId/office/templates | The template gallery for kind: Blank, the organization's own templates you can read, then the built-ins. |
POST /v1/orgs/:orgId/office/templates | Makes a file (fileId) one of the organization's templates, with an optional name and category. Editors of the file; not in personal spaces. |
DELETE /v1/orgs/:orgId/office/templates/:fileId | Takes a file off the organization's templates (the file stays). |
POST /v1/orgs/:orgId/office/imports | Opens a Word, Excel, PowerPoint, OpenDocument, CSV or Markdown file as a native one beside it (a job). |
POST /v1/orgs/:orgId/office/exports | Downloads a file in another format (a job; ask GET /jobs/:jobId until it's done, then follow result.url; Word, Excel and PowerPoint downloads list what they left out in result.left). |
GET /v1/orgs/:orgId/office/jobs/:jobId | An import or export job: status (queued, running, done, failed) and, when done, the new file or a download link. |
GET /v1/orgs/:orgId/office/recent | The person's files of a kind: recently opened first (view: recent, shared, starred or all). |
GET /v1/orgs/:orgId/office/search | Files whose content holds every word of q (and that the person can open), with a snippet. |
POST /v1/orgs/:orgId/office/assist | Writing, formula and slide help for the file's editor (a model call; counted per day). |
POST /v1/me/office/files | A new document, spreadsheet or presentation (blank, a built-in template or one of the org's), in parentId or My Drive. |
GET /v1/me/office/files/:fileId | A document, spreadsheet or presentation: its Drive item, kind, what you may do (rights: edit, comment, share) and where it is. |
POST /v1/me/office/files/:fileId/copy | Makes a copy ("Copy of …", or name) in parentId or beside it, with its pictures; versionId copies an earlier version. |
GET /v1/me/office/files/:fileId/collab | The shared document with the caller's rights and a socket ticket (ticket=0 without; state=0 for a ticket alone, on reconnects). |
POST /v1/me/office/files/:fileId/collab/seed | Sets up a file nobody has edited yet: the first update (base64 Yjs) on the version base. 409 when it's already set up. |
POST /v1/me/office/files/:fileId/collab/updates | Sends an edit (update, base64 Yjs) at epoch; answers its seq. For edits too large for the socket (over 90 KB). 409 when the epoch is stale: reload the state. |
GET /v1/me/office/files/:fileId/collab/updates | Edits after after at epoch, or { reset: true } when the file was replaced since (a restore or an upload): reload the state. |
POST /v1/me/office/files/:fileId/checkpoint | Saves a checkpoint now (a Drive version): on leaving, every 10 minutes of editing, or named. |
POST /v1/me/office/files/:fileId/media | A picture into the file: a one-part upload link, then …/complete; GET a one-hour link to it. |
POST /v1/me/office/files/:fileId/media/:mediaId/complete | Finishes a picture's upload (after the PUT to the link POST …/media answered). |
GET /v1/me/office/files/:fileId/media/:mediaId | A short-lived link to a picture in the file. |
GET /v1/me/office/files/:fileId/versions | Versions (Drive's, newest first) with names and pins, whether you may manage them, and how many changes aren't in a version yet (unsaved). |
GET /v1/me/office/files/:fileId/versions/:versionId/content | An earlier version's state (base64 Yjs) for viewing. Editors only, as in Drive. |
PATCH /v1/me/office/files/:fileId/versions/:versionId | Names (name, null to clear) or pins (pinned) a version. Pinned versions aren't pruned. |
POST /v1/me/office/files/:fileId/versions/:versionId/restore | Makes an earlier version current again (a new version with its content); open editors reload. |
GET /v1/me/office/files/:fileId/threads | Comment threads on the file, with their anchors (text, cell, slide element or point) and authors' names. |
POST /v1/me/office/files/:fileId/threads | Starts a thread at anchor with body (Markdown; @[Name](usr_…) mentions notify). Commenters and up. |
POST /v1/me/office/files/:fileId/threads/:threadId/comments | Replies to a thread (and reopens it if it was resolved). |
PATCH /v1/me/office/files/:fileId/threads/:threadId | Resolves or reopens a thread (resolved). Anyone who can comment. |
DELETE /v1/me/office/files/:fileId/threads/:threadId | Deletes a thread. Its author, or an editor of the file. |
PATCH /v1/me/office/files/:fileId/threads/:threadId/comments/:commentId | Edits your own comment (body). |
DELETE /v1/me/office/files/:fileId/threads/:threadId/comments/:commentId | Deletes a comment: your own, or any as an editor of the file. |
POST /v1/me/office/files/:fileId/mentions | People @mentioned who can't open the file yet (the commenter is asked to share first). |
GET /v1/me/office/files/:fileId/lock | Editing locks (Studio: one editor at a time; renew every minute). |
POST /v1/me/office/files/:fileId/lock | Takes or renews the editing lock for one-at-a-time editing (renew every minute). 423 with who has it when someone else does. |
DELETE /v1/me/office/files/:fileId/lock | Gives up the editing lock. |
GET /v1/me/office/templates | The template gallery for kind: Blank, the organization's own templates you can read, then the built-ins. |
POST /v1/me/office/templates | Makes a file (fileId) one of the organization's templates, with an optional name and category. Editors of the file; not in personal spaces. |
DELETE /v1/me/office/templates/:fileId | Takes a file off the organization's templates (the file stays). |
POST /v1/me/office/imports | Opens a Word, Excel, PowerPoint, OpenDocument, CSV or Markdown file as a native one beside it (a job). |
POST /v1/me/office/exports | Downloads a file in another format (a job; ask GET /jobs/:jobId until it's done, then follow result.url; Word, Excel and PowerPoint downloads list what they left out in result.left). |
GET /v1/me/office/jobs/:jobId | An import or export job: status (queued, running, done, failed) and, when done, the new file or a download link. |
GET /v1/me/office/recent | The person's files of a kind: recently opened first (view: recent, shared, starred or all). |
GET /v1/me/office/search | Files whose content holds every word of q (and that the person can open), with a snippet. |
POST /v1/me/office/assist | Writing, formula and slide help for the file's editor (a model call; counted per day). |
GET /v1/office/config | Limits for Documents, Sheets, Slides and Studio, and the download formats each kind offers now. |