Standard protocols. One revocable password.

Say who this credential acts as and what it may do

operationId getMe · App password · scopes account:read

Returns the account the credential belongs to, the organisations it is in, and for a personal API token its scopes, the one item it is limited to and when it expires. Call it first: it tells you which apps you can use before you try them.

Answer 200 application/json

account object · required

—

orgs object[] · required

The organisations the account is an active member or guest of.

credential "personalToken" | "appPassword" · required

What the request authenticated with. An app password has every scope and no limit.

scopes string[] · required

Every scope the credential holds, account:read and search:read included, which every token has.

token object | null · required

The personal API token, or null for an app password.

requestsPerMinute integer · required

How many requests the credential may make a minute.

List what this token did recently

operationId listTokenActivity · App password · scopes account:read

Returns the requests made with the calling personal API token, newest first: when, which operation, the path and the status it was answered with — refusals for a missing scope included. The last 500 are kept. An app password has no activity of its own and is answered not-found.

Parameters

cursor query · string

The nextCursor of the previous page. Absent for the first.

limit query · integer

How many items to return.

Answer 200 application/json

activity object[] · required

—

nextCursor string | null · required

Pass as ?cursor= for the next page; null on the last one.

Search every app this token can read

operationId search · App password · scopes search:read

Finds the phrase in the titles and text of boards and cards, documents, wiki pages, sites, photos, notes, calendar events, sheets, slide decks and Drive files, and returns one list, title matches first. In notes, each of its words is matched as the start of a word, in any order. Each hit says what it is, where it sits, and the URL to fetch it with. A personal token searches only the apps its scopes cover and only inside the item it is limited to; skipped says which apps were left out and why.

Parameters

q query · string · required

The phrase to find.

apps query · string

Only these apps, comma-separated: tasks, docs, wiki, sites, photos, notes, calendar, sheets, slides, drive.

limit query · integer

How many hits to return, at most 50.

Answer 200 application/json

hits object[] · required

—

searched "tasks" | "docs" | "wiki" | "sites" | "photos" | "notes" | "calendar" | "sheets" | "slides" | "drive"[] · required

The apps that were searched.

skipped object[] · required

The apps that were not searched for this credential, and why.

List the boards this account is on

operationId listBoards · App password · scopes tasks:read

Returns every board the account owns or was invited to, archived ones included, with the account's role on each and its count of open cards. Start here to find a board's id; then getBoard reads its lists, labels, members and cards.

Parameters

cursor query · string

The nextCursor of the previous page. Absent for the first.

limit query · integer

How many items to return.

Answer 200 application/json

boards BoardSummary[] · required

—

nextCursor string | null · required

Pass as ?cursor= for the next page; null on the last one.

Create a board

operationId createBoard · App password · scopes tasks:write

Makes a new, empty board owned by this account and answers its id. Add lists with createList before adding cards.

Parameters

Idempotency-Key header · string

Any unique string up to 255 characters. A POST retried with the same key and body within 24 hours answers what the first one did, without doing it again.

Request body application/json

name string · required

—

colour string

A preset colour's name, or #rrggbb.

Answer 201 application/json

board object · required

—

Read a board with its lists, labels, members and open cards

operationId getBoard · App password · scopes tasks:read

Returns the whole board in one answer: its lists in order, its labels, its custom fields, its members' names and roles, and every open card. Use it to learn the list, label and member ids that createCard and updateCard take.

Parameters

boardId path · string · required

The board's id, as listBoards answers it.

Answer 200 application/json

board object · required

—

lists List[] · required

—

labels Label[] · required

—

fields object[] · required

—

members object[] · required

—

cards Card[] · required

—

Add a list to a board

operationId createList · App password · scopes tasks:write

Adds a list at the right end of the board and answers its id, which createCard takes as listId. Needs the editor role on the board.

Parameters

boardId path · string · required

The board's id, as listBoards answers it.

Idempotency-Key header · string

Any unique string up to 255 characters. A POST retried with the same key and body within 24 hours answers what the first one did, without doing it again.

Request body application/json

name string · required

—

Answer 201 application/json

list object · required

—

List a board's open cards

operationId listCards · App password · scopes tasks:read

Returns the board's open cards — not archived ones — in board order, optionally only one list's. Each card is its summary; getCard reads one in full with its description, checklists and comments.

Parameters

boardId path · string · required

The board's id, as listBoards answers it.

cursor query · string

The nextCursor of the previous page. Absent for the first.

limit query · integer

How many items to return.

listId query · string

Only this list's cards.

Answer 200 application/json

cards Card[] · required

—

nextCursor string | null · required

Pass as ?cursor= for the next page; null on the last one.

Create a card

operationId createCard · App password · scopes tasks:write

Adds a card at the bottom of a list, with an optional description and dates, and answers it in full. The board's automation rules and webhooks run as they do for a card made in the app. Needs the editor role.

Parameters

boardId path · string · required

The board's id, as listBoards answers it.

Idempotency-Key header · string

Any unique string up to 255 characters. A POST retried with the same key and body within 24 hours answers what the first one did, without doing it again.

Request body application/json

listId string · required

The list it goes at the bottom of.

title string · required

—

description string

Markdown.

dueAt string | null

A day, YYYY-MM-DD, or null.

startAt string | null

A day, YYYY-MM-DD, or null.

Answer 201 application/json

card CardDetail · required

—

Read a card in full

operationId getCard · App password · scopes tasks:read

Returns one card with its description, checklists, comments, attachments and links to other cards. The ETag it answers can be sent as If-Match on updateCard.

Parameters

boardId path · string · required

The board's id, as listBoards answers it.

cardId path · string · required

The card's id.

Answer 200 application/json

card CardDetail · required

—

Change a card: title, description, list, dates, labels, assignees, done or archived

operationId updateCard · App password · scopes tasks:write

A partial update: only the keys sent change. Moving is listId (and beforeCardId to place it above a card); completed: true ticks it off; archived: true archives it. labelIds and assigneeIds replace the whole set. Answers the card as it now is. Rules and webhooks run as they do in the app. A card has no version: If-Match is compared with the card as it is just before the write, which catches a change made since you read it but not one made in the same instant.

Parameters

boardId path · string · required

The board's id, as listBoards answers it.

cardId path · string · required

The card's id.

If-Match header · string

The ETag the item was read at. When it is sent and the item has changed since, the write is refused with 412.

Request body application/json

title string

—

description string

Markdown.

listId string

Move the card to this list.

beforeCardId string | null

With listId: place it above this card. Null or absent puts it at the bottom.

fromListId string

With listId: the list you saw it in. A card that moved since is refused rather than moved twice.

dueAt string | null

A day, YYYY-MM-DD, or null to clear it.

startAt string | null

A day, YYYY-MM-DD, or null to clear it.

completed boolean

Tick the card off, or reopen it.

archived boolean

Archive the card, or bring it back.

labelIds string[]

The card's labels: replaces the whole set.

assigneeIds string[]

The card's assignees, as member ids: replaces the whole set.

Answer 200 application/json

card CardDetail · required

—

Delete a card for good

operationId deleteCard · App password · scopes tasks:write

Deletes the card, its checklists and its comments. This cannot be undone; to keep it out of sight but restorable, use updateCard with archived: true instead.

Parameters

boardId path · string · required

The board's id, as listBoards answers it.

cardId path · string · required

The card's id.

If-Match header · string

The ETag the item was read at. When it is sent and the item has changed since, the write is refused with 412.

Answer 204

List the documents this account can open

operationId listDocs · App password · scopes docs:read

Returns the documents the account owns or was invited to, most recently changed first, without their bodies. q narrows them to titles containing the words. getDoc reads one with its body.

Parameters

cursor query · string

The nextCursor of the previous page. Absent for the first.

limit query · integer

How many items to return.

q query · string

Only documents whose title contains this.

Answer 200 application/json

docs DocSummary[] · required

—

nextCursor string | null · required

Pass as ?cursor= for the next page; null on the last one.

Create a document

operationId createDoc · App password · scopes docs:write

Makes a document — empty, or with a body in the editor's JSON — in the account's Drive, or as a page under parentDocId. Answers it in full with its version.

Parameters

Idempotency-Key header · string

Any unique string up to 255 characters. A POST retried with the same key and body within 24 hours answers what the first one did, without doing it again.

Request body application/json

name string · required

The title. No slashes.

body object

The body in the editor's JSON. Absent for an empty document.

parentDocId string

Make it a page under this document. Needs the editor role there.

Answer 201 application/json

doc Doc · required

—

Read a document with its body

operationId getDoc · App password · scopes docs:read

Returns the document's name, version and body in the editor's JSON. The ETag is its version: send it as If-Match when you write the body back with updateDoc.

Parameters

docId path · string · required

The document's id, as listDocs answers it.

Answer 200 application/json

doc Doc · required

—

Rename a document or replace its body

operationId updateDoc · App password · scopes docs:write

A partial update: name renames it; body replaces the whole text and must say which version it was written against, as If-Match (or baseVersion in the body), so a change somebody made since is never overwritten — that answers 412 with the version it is at now. Answers the document as it now is.

Parameters

docId path · string · required

The document's id, as listDocs answers it.

If-Match header · string

The ETag the item was read at. When it is sent and the item has changed since, the write is refused with 412.

Request body application/json

name string

A new title.

body object

The whole new body, in the editor's JSON.

baseVersion integer

Deprecated: send the version as If-Match instead.

Answer 200 application/json

doc Doc · required

—

Move a document to the bin

operationId deleteDoc · App password · scopes docs:write

Moves the document to its owner's bin, where Drive can restore it until the bin is emptied. Only the owner may.

Parameters

docId path · string · required

The document's id, as listDocs answers it.

If-Match header · string

The ETag the item was read at. When it is sent and the item has changed since, the write is refused with 412.

Answer 204

List a document's comment threads

operationId listDocComments · App password · scopes docs:read

Returns the comment threads on the document, open ones first, each with the text it was opened on and its comments in order.

Parameters

docId path · string · required

The document's id, as listDocs answers it.

cursor query · string

The nextCursor of the previous page. Absent for the first.

limit query · integer

How many items to return.

Answer 200 application/json

threads CommentThread[] · required

—

nextCursor string | null · required

Pass as ?cursor= for the next page; null on the last one.

List the wiki spaces this account can open

operationId listWikiSpaces · App password · scopes wiki:read

Returns the account's own spaces and those it was given a role in, with their page counts. Start here to find a space's id.

Parameters

cursor query · string

The nextCursor of the previous page. Absent for the first.

limit query · integer

How many items to return.

Answer 200 application/json

spaces WikiSpace[] · required

—

nextCursor string | null · required

Pass as ?cursor= for the next page; null on the last one.

List the pages of a space

operationId listWikiPages · App password · scopes wiki:read

Returns the pages this account may see in the space, in the sidebar's order with the home page first, without their text. Restricted pages and other people's drafts are left out, as in the app.

Parameters

spaceId path · string · required

The space's id, as listWikiSpaces answers it.

cursor query · string

The nextCursor of the previous page. Absent for the first.

limit query · integer

How many items to return.

Answer 200 application/json

pages WikiPage[] · required

—

nextCursor string | null · required

Pass as ?cursor= for the next page; null on the last one.

Create a wiki page

operationId createWikiPage · App password · scopes wiki:write

Makes a page with a title and optional Markdown, at the top of the space or under parentId, published or as a draft. Needs the editor role in the space and on the page it goes under.

Parameters

spaceId path · string · required

The space's id, as listWikiSpaces answers it.

Idempotency-Key header · string

Any unique string up to 255 characters. A POST retried with the same key and body within 24 hours answers what the first one did, without doing it again.

Request body application/json

title string · required

—

body string

The page's Markdown.

parentId string | null

The page it goes under; null for the top of the space.

status "current" | "draft"

A draft is seen only by the space's editors until it is published.

Answer 201 application/json

page WikiPage · required

—

Read a wiki page as Markdown

operationId getWikiPage · App password · scopes wiki:read

Returns the page's Markdown — or, with Accept: application/json, the page's details with its Markdown in body. The ETag is its version; If-None-Match with it answers 304 when nothing changed. Send the ETag as If-Match to replaceWikiPage.

Parameters

spaceId path · string · required

The space's id, as listWikiSpaces answers it.

pageId path · string · required

The page's id, as listWikiPages answers it.

If-None-Match header · string

An ETag you hold. When the page is still at it, the answer is 304 with no body.

Answer 200 application/json, text/markdown

page object · required

—

Replace a wiki page's Markdown

operationId replaceWikiPage · App password · scopes wiki:write

Writes new Markdown over the page, sent as text/markdown or as JSON with a body member. If-Match is required and names the version you read; If-Match: * overwrites whatever is there. A page changed since answers 412 with its version; a conflicting save kept as a copy answers 409 with the copy's id.

Parameters

spaceId path · string · required

The space's id, as listWikiSpaces answers it.

pageId path · string · required

The page's id, as listWikiPages answers it.

If-Match header · string · required

The ETag the item was read at. Required: without it the answer is 428, and with a stale one 412.

Request body text/markdown, application/json

body string · required

The page's new Markdown.

Answer 200 application/json

status "saved" | "unchanged" · required

unchanged when the text was already this.

version number · required

—

Search a space's pages

operationId searchWiki · App password · scopes wiki:read

Returns the pages in the space that hold every word of q, best first, verified pages ranked above the rest — never a page the account could not open. Narrow with tag, status and since; it finds at most the 100 best matches. Use it to find a page before reading it with getWikiPage.

Parameters

spaceId path · string · required

The space's id, as listWikiSpaces answers it.

cursor query · string

The nextCursor of the previous page. Absent for the first.

limit query · integer

How many items to return.

q query · string

The words to look for.

tag query · string

Only pages with this tag.

status query · "current" | "draft" | "deprecated" | "verified" | "due"

Only pages in this state; verified and due are about review.

since query · string

Only pages changed since this ISO 8601 date.

Answer 200 application/json

results object[] · required

—

nextCursor string | null · required

Pass as ?cursor= for the next page; null on the last one.

List or search the account's notes

operationId listNotes · App password · scopes notes:read

Returns the account's own notes, pinned first and then the most recently changed, each with its title, an excerpt, its tags and version but not its whole text. q searches as Notes does — every word must appear, and operators such as tag:, folder:, is: and has: narrow it. Read one whole with getNote. Notes others shared with the account are read by id and not listed here.

Parameters

cursor query · string

The nextCursor of the previous page. Absent for the first.

limit query · integer

How many items to return.

q query · string

A search, as Notes' own search box takes it: words that must all appear, and operators such as tag:work, folder:Projects, is:pinned, is:open, has:checklist, before:2026-10-01 and after:2026-09-01.

tag query · string

Only notes carrying this tag.

kind query · "note" | "list"

note opens as prose; list opens as a checklist. The text is the same Markdown either way.

archived query · "exclude" | "include" | "only"

Whether archived notes are listed. Without q the default is exclude, as on the Notes home; with q it is include, as in its search.

Answer 200 application/json

notes object[] · required

—

nextCursor string | null · required

Pass as ?cursor= for the next page; null on the last one.

Write a new note

operationId createNote · App password · scopes notes:write

Makes a note from Markdown, in the Notes folder unless folderId names another of the account's Drive folders, with tags, a colour and a pin if given. Its first line is its title. The note is in its history as made through the token.

Parameters

Idempotency-Key header · string

Any unique string up to 255 characters. A POST retried with the same key and body within 24 hours answers what the first one did, without doing it again.

Request body application/json

text string · required

The note's Markdown. Its first line is its title and names its file.

kind "note" | "list"

note opens as prose; list opens as a checklist. The text is the same Markdown either way.

folderId string

The Drive folder to file it in. Absent files it in the Notes folder — or, for a token limited to a folder, in that folder.

tags string[]

The note's tags, as they should read. Replaces the tags it has; an empty list removes them all.

colour "teal" | "cyan" | "violet" | "amber" | "red" | "green" | null

The note's colour label, or null for none.

pinned boolean

Pinned to the top of the Notes home.

Answer 201 application/json

note object · required

—

List the tags on the account's notes

operationId listNoteTags · App password · scopes notes:read

Returns every tag on at least one of the account's notes with how many carry it, most used first. Filter listNotes by one with tag=, or set a note's tags with updateNote.

Parameters

cursor query · string

The nextCursor of the previous page. Absent for the first.

limit query · integer

How many items to return.

Answer 200 application/json

tags object[] · required

—

nextCursor string | null · required

Pass as ?cursor= for the next page; null on the last one.

Add Markdown to the end of today's note

operationId appendToTodaysNote · App password · scopes notes:write

Finds the daily note for date — today when absent — or makes it from the account's daily template, and adds text as a new paragraph at its end. Applied to the note as it is, so it needs no If-Match and cannot conflict with an open editor. Answers the note with its new version.

Parameters

Idempotency-Key header · string

Any unique string up to 255 characters. A POST retried with the same key and body within 24 hours answers what the first one did, without doing it again.

Request body application/json

text string · required

Markdown to add as a new paragraph at the end of the note.

date string

The day whose note to add to, as YYYY-MM-DD. Absent means today, in the server's time zone (Europe/Berlin).

Answer 200 application/json

note object · required

—

created boolean · required

Whether the day's note was made by this call.

Read a note as Markdown

operationId getNote · App password · scopes notes:read

Returns the note's Markdown — or, with Accept: application/json, its details with the Markdown in body. The ETag is its version; If-None-Match with it answers 304 when nothing changed. Send the ETag as If-Match to updateNote. A note shared with the account is read the same way.

Parameters

noteId path · string · required

The note's id, as listNotes answers it.

If-None-Match header · string

An ETag you hold. When the note is still at it, the answer is 304 with no body.

Answer 200 application/json, text/markdown

note object · required

—

Change a note's text, tags, colour, pin or archive

operationId updateNote · App password · scopes notes:write

Changes the members sent and leaves the rest. Replacing text needs If-Match with the version you read (or * for whatever is there): a save made since answers 412 with the version it is at now, and nothing is changed. Tags, colour, pinned, archived and kind are the owner's to change; an editor of a shared note may change its text. The change is in the note's history, marked with the token's name.

Parameters

noteId path · string · required

The note's id, as listNotes answers it.

If-Match header · string

The ETag the item was read at. When it is sent and the item has changed since, the write is refused with 412.

Request body application/json

text string

The note's whole new Markdown. Needs If-Match with the version it was read at.

kind "note" | "list"

note opens as prose; list opens as a checklist. The text is the same Markdown either way.

tags string[]

The note's tags, as they should read. Replaces the tags it has; an empty list removes them all.

colour "teal" | "cyan" | "violet" | "amber" | "red" | "green" | null

The note's colour label, or null for none.

pinned boolean

—

archived boolean

Archived: off the Notes home, still found by search.

Answer 200 application/json

note object · required

—

outcome "saved" | "unchanged" · required

unchanged: the note already held this text, and nothing was written.

Put a note in the bin

operationId deleteNote · App password · scopes notes:write

Moves the note to its owner's bin, where it can be restored from Drive until the bin is emptied. Only the owner may. If-Match, when sent, must name the version the note is at.

Parameters

noteId path · string · required

The note's id, as listNotes answers it.

If-Match header · string

The ETag the item was read at. When it is sent and the item has changed since, the write is refused with 412.

Answer 204

Add Markdown to the end of a note

operationId appendToNote · App password · scopes notes:write

Adds text as a new paragraph at the end of the note, applied to the note as it is now: no If-Match, and no conflict with someone typing in it. Answers the note with its new version. To add to the day's note without knowing its id, use appendToTodaysNote.

Parameters

noteId path · string · required

The note's id, as listNotes answers it.

Idempotency-Key header · string

Any unique string up to 255 characters. A POST retried with the same key and body within 24 hours answers what the first one did, without doing it again.

Request body application/json

text string · required

Markdown to add as a new paragraph at the end of the note.

Answer 200 application/json

note object · required

—

List the notes a note links to, and those linking to it

operationId getNoteLinks · App password · scopes notes:read

Returns the notes this one links to with [[Title]] or a note link (outlinks, at most 100) and the notes that link to it (backlinks, the 50 most recently changed). Each is an id to read with getNote.

Parameters

noteId path · string · required

The note's id, as listNotes answers it.

Answer 200 application/json

outlinks object[] · required

—

backlinks object[] · required

—

List the spreadsheets this account can open

operationId listSpreadsheets · App password · scopes sheets:read

Returns the spreadsheets the account owns or that are shared with it, most recently changed first, with its role on each and their version. q narrows them by name. getSpreadsheet lists one's tabs; getSheetValues reads its cells.

Parameters

cursor query · string

The nextCursor of the previous page. Absent for the first.

limit query · integer

How many items to return.

q query · string

Only spreadsheets whose name holds this text.

Answer 200 application/json

spreadsheets object[] · required

—

nextCursor string | null · required

Pass as ?cursor= for the next page; null on the last one.

Make a spreadsheet

operationId createSpreadsheet · App password · scopes sheets:write

Makes a spreadsheet of one empty tab in the account's Drive — at the top unless folderId names one of its folders — optionally starting with values from A1, formulas calculated. The spreadsheet's history says it was made through the token.

Parameters

Idempotency-Key header · string

Any unique string up to 255 characters. A POST retried with the same key and body within 24 hours answers what the first one did, without doing it again.

Request body application/json

name string

The spreadsheet's name. Absent names it Untitled spreadsheet.

folderId string

The Drive folder to make it in. Absent makes it at the top of Drive — or, for a token limited to a folder, in that folder.

values number | string | boolean | null[][]

Cells to start the first tab with, from A1, as writeSheetValues takes them.

Answer 201 application/json

spreadsheet object · required

—

Read a spreadsheet's details and its tabs

operationId getSpreadsheet · App password · scopes sheets:read

Returns the spreadsheet with each of its tabs: id, name, size, the range holding something, and whether it is protected. The ETag is its version, which writeSheetValues needs as If-Match. A spreadsheet past 4 MB to read, or 2 MB or 10 000 formulas to write, is refused as file-too-large: open it in Sheets.

Parameters

sheetId path · string · required

The spreadsheet's id, as listSpreadsheets answers it.

Answer 200 application/json

spreadsheet object · required

—

Read a range of cells

operationId getSheetValues · App password · scopes sheets:read

Returns the cells of range on tab, row by row — as last calculated, or with render=formulas each formula in A1 notation. Without range, every cell of the tab that holds something. A page is limit rows, and fewer when that would pass 10 000 cells; nextCursor reads on. The ETag is the spreadsheet's version. A spreadsheet past 4 MB to read, or 2 MB or 10 000 formulas to write, is refused as file-too-large: open it in Sheets.

Parameters

sheetId path · string · required

The spreadsheet's id, as listSpreadsheets answers it.

cursor query · string

The nextCursor of the previous page. Absent for the first.

limit query · integer

How many items to return.

tab query · string

The tab, by its name or its id. Absent means the first tab.

range query · string

The cells to read, in A1 notation such as A1:D20. Absent means every cell of the tab that holds something.

render query · "values" | "formulas"

values: what each cell shows, as last calculated. formulas: a formula cell's formula in A1 notation, and the value of any other cell.

Answer 200 application/json

tab object · required

—

range string | null · required

The cells this page holds, in A1 notation; null for an empty tab.

values number | string | boolean | null | object[][] · required

—

version integer · required

—

nextCursor string | null · required

Pass as ?cursor= for the next page; null on the last one.

Write a range of cells

operationId writeSheetValues · App password · scopes sheets:write

Writes values into tab from range's top-left cell, as typing them would: text starting with = is a formula, null clears a cell, and the tab grows to fit. The written cells and every formula reading them are recalculated. If-Match is the version you read; a save made since answers 412 with the version it is at now. Protected ranges hold: writing a cell the account may not change is refused as forbidden, and nothing is written. At most 10 000 cells a call. Anyone editing the spreadsheet in Sheets at that moment is asked to reload, and what they typed in the last few seconds is lost, so write in batches rather than cell by cell. The change is in the spreadsheet's history, marked with the token's name. A spreadsheet past 4 MB to read, or 2 MB or 10 000 formulas to write, is refused as file-too-large: open it in Sheets.

Parameters

sheetId path · string · required

The spreadsheet's id, as listSpreadsheets answers it.

If-Match header · string · required

The ETag the item was read at. Required: without it the answer is 428, and with a stale one 412.

Request body application/json

tab string

The tab, by its name or its id. Absent means the first tab.

range string · required

Where to write: the top-left cell, such as B2, or the whole rectangle, which values must then fill exactly.

values number | string | boolean | null[][] · required

Rows of cells: a number, text, true or false, or null to clear the cell. Rows may differ in length; a missing cell is left as it is.

input "user" | "raw"

user (the default): text starting with = is a formula. raw: every text is stored as text, = and all. Either way any other text stays text — send a number as a JSON number and true or false as a JSON boolean.

Answer 200 application/json

version integer · required

—

range string · required

The cells written, in A1 notation.

cells integer · required

Cells set or cleared.

List the sites this account can edit

operationId listSites · App password · scopes sites:read

Returns the account's own sites and those it was invited to, with its role on each, where each answers and whether it is live. Start here to find a site's id.

Parameters

cursor query · string

The nextCursor of the previous page. Absent for the first.

limit query · integer

How many items to return.

Answer 200 application/json

sites Site[] · required

—

nextCursor string | null · required

Pass as ?cursor= for the next page; null on the last one.

Read a site

operationId getSite · App password · scopes sites:read

Returns one site: its address, whether it is live, a scheduled publish, and its version. The ETag is the version; send it as If-Match to publishSite to publish only the site you looked at.

Parameters

siteId path · string · required

The site's id, as listSites answers it.

Answer 200 application/json

site Site · required

—

List a builder site's pages and posts

operationId listSitePages · App password · scopes sites:read

Returns the pages and blog posts of a site made in the page builder, in menu order, without their bodies. A site published from a folder of files has no pages and answers 409.

Parameters

siteId path · string · required

The site's id, as listSites answers it.

cursor query · string

The nextCursor of the previous page. Absent for the first.

limit query · integer

How many items to return.

Answer 200 application/json

pages SitePage[] · required

—

nextCursor string | null · required

Pass as ?cursor= for the next page; null on the last one.

Read a site page with its body

operationId getSitePage · App password · scopes sites:read

Returns one builder page with its body — the sections and blocks the editor shows — and its version as the ETag, which replaceSitePage needs as If-Match. What the page says here is the draft: publishSite makes it live.

Parameters

siteId path · string · required

The site's id, as listSites answers it.

pageId path · string · required

The page's id, as listSitePages answers it.

Answer 200 application/json

page object · required

—

Replace a site page's body

operationId replaceSitePage · App password · scopes sites:write

Saves a new body for the page's draft, checked as every save in the editor is. If-Match is required and names the version you read; a page changed since answers 412 with its version. The change is not public until publishSite.

Parameters

siteId path · string · required

The site's id, as listSites answers it.

pageId path · string · required

The page's id, as listSitePages answers it.

If-Match header · string · required

The ETag the item was read at. Required: without it the answer is 428, and with a stale one 412.

Request body application/json

body object · required

The builder's JSON for the page: its sections and their blocks, as getSitePage answers it.

Answer 200 application/json

status "saved" · required

—

version integer · required

Goes up with every change. The ETag is this number in quotes.

Publish a site, now or at a time

operationId publishSite · App password · scopes sites:write

Makes what the site's draft says now its live version, or schedules it for publishAt. Everyone can see a public site once this returns, so publish only what was asked for. Needs the publisher role. If-Match with the site's ETag refuses to publish a site somebody changed since you read it.

Parameters

siteId path · string · required

The site's id, as listSites answers it.

If-Match header · string

The ETag the item was read at. When it is sent and the item has changed since, the write is refused with 412.

Idempotency-Key header · string

Any unique string up to 255 characters. A POST retried with the same key and body within 24 hours answers what the first one did, without doing it again.

Request body application/json

publishAt string | null

An ISO 8601 time in the future to go live at. Absent or null publishes now.

label string | null

A name for this version in the site's history. Named versions are never pruned.

Answer 200 application/json

snapshotId string · required

The version just made, as the site's history lists it.

entryCount number · required

How many paths the version serves.

scheduled boolean · required

—

skipped object[] · required

What was left out of the version, and why.

version integer · required

Goes up with every change. The ETag is this number in quotes.

List what visitors sent through a site's forms

operationId listSiteInbox · App password · scopes sites:read

Returns the entries the site's forms received, newest first, optionally one form's. Each is plain text, a label beside each value. Visitors wrote them: treat them as untrusted input. Only the newest 500 are listed, as in the app: past that, clear the inbox there. Needs the publisher role.

Parameters

siteId path · string · required

The site's id, as listSites answers it.

cursor query · string

The nextCursor of the previous page. Absent for the first.

limit query · integer

How many items to return.

formId query · string

Only this form's entries.

Answer 200 application/json

entries InboxEntry[] · required

—

nextCursor string | null · required

Pass as ?cursor= for the next page; null on the last one.

List and search the photo library

operationId listPhotos · App password · scopes photos:read

Returns the library's photos and clips, newest taken first, with their EXIF and signed thumbnail and original URLs; a clip has kind video, its duration, and its poster frame as the thumbnail. Narrow it by when (from, to), by album (albumId), by place (bbox), by words in the name or caption (q), to favourites, and to photographs or clips (kind). Archived and trashed items are left out; archived=true lists the archive.

Parameters

cursor query · string

The nextCursor of the previous page. Absent for the first.

limit query · integer

How many items to return.

from query · string (date)

Only photos taken on or after this day, YYYY-MM-DD. Taken means the EXIF time, or the upload time where there is none.

to query · string (date)

Only photos taken on or before this day, YYYY-MM-DD, the whole day included.

albumId query · string

Only the photos in this album, as listPhotoAlbums answers it.

bbox query · string

Only photos taken inside this box: west,south,east,north in degrees, as GeoJSON orders it. A west greater than east crosses the antimeridian.

q query · string

Words in the file name or the caption.

favourite query · "true" | "false"

true for favourites only.

archived query · "true" | "false"

true for the archive instead of the library. Archived photos are left out otherwise.

kind query · "photo" | "video"

photo for photographs only, video for clips only. Both when absent.

Answer 200 application/json

photos object[] · required

—

nextCursor string | null · required

Pass as ?cursor= for the next page; null on the last one.

Upload a photo or clip into the library

operationId uploadPhoto · App password · scopes photos:write

The body is the image or clip itself, with its own Content-Type (JPEG, PNG, GIF, WebP, AVIF, BMP, HEIC or HEIF; MP4, QuickTime or WebM for a clip) and Content-Length, up to 64 MB. The server never reads an image or a video, so send the metadata you read locally as query parameters: they are checked and bounded, and a value no camera could have recorded is dropped rather than refused — the answer's metadata says what was kept. A clip uploaded here has no poster frame, so its thumbnail is null. Its location is not blanked either: a share link that strips metadata will not play it unless you blanked every location box before sending it and say so with scrubbed=true. With contentHash, an item already in the library is answered with 200 and status duplicate instead of stored again, which makes a retry safe; an Idempotency-Key needs contentHash. The answer's signed URLs expire in minutes: read the photo again for fresh ones.

Parameters

name query · string · required

The file name, with its extension.

albumId query · string

An album to file the photo in once it is stored.

contentHash query · string

The SHA-256 of the bytes, lowercase hex. A photo with the same hash already in the library is answered instead of stored twice.

takenAt query · string

When it was taken, ISO 8601, from EXIF DateTimeOriginal.

width query · string

Width in pixels.

height query · string

Height in pixels.

camera query · string

The camera's make and model.

lens query · string

The lens.

iso query · string

ISO speed.

aperture query · string

The f-number: 2.8 for f/2.8.

focalLength query · string

Focal length in millimetres, as recorded.

latitude query · string

Where it was taken, decimal degrees. Kept only together with longitude.

longitude query · string

Where it was taken, decimal degrees. Kept only together with latitude.

caption query · string

A caption the file carried.

duration query · string

A clip's length in seconds, from its mvhd box. Ignored for a photograph.

scrubbed query · "true" | "false"

true if you blanked every location box in the clip before sending it, as the app's uploader does. A share link that strips metadata plays only such a clip; it is your word, and nothing on the server checks it. Ignored for a photograph.

Idempotency-Key header · string

Any unique string up to 255 characters. A POST retried with the same key and body within 24 hours answers what the first one did, without doing it again.

Request body image/*, video/*

Answer 201 application/json

status "stored" | "duplicate" · required

duplicate when the library already held a photo with this contentHash; photo is then that one.

photo object · required

—

metadata object · required

What was kept of the metadata sent; null where a value was absent or not believable.

Read a photo with its EXIF

operationId getPhoto · App password · scopes photos:read

Returns one photo: its EXIF, place, rating and caption, the albums it is in, and signed URLs for a thumbnail, a 1280-pixel preview and the original. The ETag changes with any change to the photo; send it as If-Match to updatePhoto or deletePhoto to change only the photo you read.

Parameters

photoId path · string · required

The photo's id, as listPhotos answers it.

Answer 200 application/json

photo object · required

—

Favourite, rate, caption or correct a photo

operationId updatePhoto · App password · scopes photos:write

Changes the fields sent and leaves the rest: favourite, rating, archived, caption, alt text, when it was taken and where. A time or a place no camera could have recorded is stored as none. If-Match with the photo's ETag refuses the change when the photo changed since you read it.

Parameters

photoId path · string · required

The photo's id, as listPhotos answers it.

If-Match header · string

The ETag the item was read at. When it is sent and the item has changed since, the write is refused with 412.

Request body application/json

favourite boolean

Mark or unmark it as a favourite.

rating integer

Stars, 0 to 5; 0 clears the rating.

archived boolean

Move it to the archive, out of the library's timeline, or back.

caption string | null

The caption; null or empty clears it.

altText string | null

A description for people who cannot see it; null clears it.

takenAt string | null

Correct when it was taken, ISO 8601. A time no camera could have recorded is stored as none.

location object | null

Where it was taken; null removes the position.

Answer 200 application/json

photo object · required

—

Move a photo to the bin

operationId deletePhoto · App password · scopes photos:write

Moves the photo, and any virtual copies of it, to the bin, where it can be restored in the app until the bin is emptied. Its share links stop working. If-Match with the photo's ETag refuses when it changed since you read it.

Parameters

photoId path · string · required

The photo's id, as listPhotos answers it.

If-Match header · string

The ETag the item was read at. When it is sent and the item has changed since, the write is refused with 412.

Answer 204

Get a signed URL of a photo's original

operationId getPhotoOriginal · App password · scopes photos:read

Answers a short-lived signed URL of the bytes exactly as uploaded, without any edit — for a clip, the video. Fetch it directly, without the token. On a server with no CDN to sign for, the answer is the bytes themselves, with the photo's own Content-Type.

Parameters

photoId path · string · required

The photo's id, as listPhotos answers it.

Answer 200 application/json, image/*, video/*

url string · required

A signed CDN URL. Fetch it directly, without the token, before expiresAt.

expiresAt string (date-time) · required

—

Get a signed URL of a photo's thumbnail

operationId getPhotoThumbnail · App password · scopes photos:read

Answers a short-lived signed URL of a resized copy: a square crop at 160, 320 or 640 pixels, or the whole frame at 1280. An edited photo is shown edited, and a clip by its poster frame. On a server with no CDN to sign for, the answer is the image itself. A HEIC uploaded through the API has nothing to resize until the app has made a copy of it, and a clip uploaded through the API has no poster frame: both answer 409.

Parameters

photoId path · string · required

The photo's id, as listPhotos answers it.

size query · "160" | "320" | "640" | "1280"

Width in pixels. 160, 320 and 640 are square crops, as the grid draws them; 1280 keeps the photo's shape.

Answer 200 application/json, image/*

url string · required

A signed CDN URL. Fetch it directly, without the token, before expiresAt.

expiresAt string (date-time) · required

—

Make a share link for a photo

operationId sharePhoto · App password · scopes photos:write

Makes a link anybody who has it can open, until it expires or is revoked: by default for 7 days, without the photo's EXIF and GPS, and showing the edit. Hand the link only to whom it was asked for. An organisation's rules may require a password or an expiry, and refuse the link otherwise. A clip whose location was not blanked before upload (scrubbed false) cannot be shared with its metadata stripped, and answers 409: share it with stripMetadata false, or upload it scrubbed.

Parameters

photoId path · string · required

The photo's id, as listPhotos answers it.

Idempotency-Key header · string

Any unique string up to 255 characters. A POST retried with the same key and body within 24 hours answers what the first one did, without doing it again.

Request body application/json

expiresIn "1h" | "1d" | "7d" | "30d" | "never"

How long the link lasts: 1h, 1d, 7d, 30d or never. 7d when absent.

password string

A password the visitor must type, at least 8 characters. Absent or empty for none.

allowDownload boolean

Whether the visitor may download the photos. true when absent.

stripMetadata boolean

Remove EXIF, and with it any GPS position, from what the link serves. true when absent.

variant "edited" | "original"

Serve the edited photo or the untouched original. edited when absent.

Answer 201 application/json

share object · required

—

List the albums

operationId listPhotoAlbums · App password · scopes photos:read

Returns every album, nested ones included with their parentId, in the order the app shows them, with how many photos each holds. Start here to find an album's id; listPhotos with albumId lists its photos.

Parameters

cursor query · string

The nextCursor of the previous page. Absent for the first.

limit query · integer

How many items to return.

Answer 200 application/json

albums object[] · required

—

nextCursor string | null · required

Pass as ?cursor= for the next page; null on the last one.

Make an album

operationId createPhotoAlbum · App password · scopes photos:write

Makes an empty album, at the top level or inside another. Its name must be unique among its siblings; a second album of the same name answers 409. Add photos with addPhotosToAlbum.

Parameters

Idempotency-Key header · string

Any unique string up to 255 characters. A POST retried with the same key and body within 24 hours answers what the first one did, without doing it again.

Request body application/json

name string · required

The album's name, unique among its siblings.

description string | null

A line or two about it.

parentId string | null

The album to make it in; absent or null for the top level.

Answer 201 application/json

album object · required

—

Read an album

operationId getPhotoAlbum · App password · scopes photos:read

Returns one album: its name, description, cover and counts. Its photos are listPhotos with albumId. The ETag changes with the album; send it as If-Match to change or delete only the album you read.

Parameters

albumId path · string · required

The album's id, as listPhotoAlbums answers it.

Answer 200 application/json

album object · required

—

Rename, describe, move or choose a cover for an album

operationId updatePhotoAlbum · App password · scopes photos:write

Changes the fields sent and leaves the rest. A cover must be a photo in the album; parentId moves the album, and not into itself or an album inside it. A name its new siblings already use answers 409.

Parameters

albumId path · string · required

The album's id, as listPhotoAlbums answers it.

If-Match header · string

The ETag the item was read at. When it is sent and the item has changed since, the write is refused with 412.

Request body application/json

name string

A new name.

description string | null

A new description; null or empty clears it.

parentId string | null

Move it under this album; null for the top level.

coverPhotoId string | null

The photo its tile shows, one of its own; null for the newest.

Answer 200 application/json

album object · required

—

Delete an album

operationId deletePhotoAlbum · App password · scopes photos:write

Deletes the album, the albums inside it and their share links, for good. The photos stay in the library. If-Match with the album's ETag refuses when it changed since you read it.

Parameters

albumId path · string · required

The album's id, as listPhotoAlbums answers it.

If-Match header · string

The ETag the item was read at. When it is sent and the item has changed since, the write is refused with 412.

Answer 204

Add photos to an album

operationId addPhotosToAlbum · App password · scopes photos:write

Files up to 500 photos in the album, after those already there. A photo already in it stays where it is, and an id that is no photo in this library is skipped; inAlbum counts how many of those sent are in the album now.

Parameters

albumId path · string · required

The album's id, as listPhotoAlbums answers it.

Idempotency-Key header · string

Any unique string up to 255 characters. A POST retried with the same key and body within 24 hours answers what the first one did, without doing it again.

Request body application/json

photoIds string[] · required

The photos to file in the album, up to 500. Ids that are not photos in this library are skipped.

Answer 200 application/json

inAlbum number · required

How many of the photos sent are in the album now.

Take a photo out of an album

operationId removePhotoFromAlbum · App password · scopes photos:write

Takes the photo out of the album; the photo itself stays in the library. Answers 404 when it was not in the album. If-Match with the album's ETag refuses when the album changed since you read it.

Parameters

albumId path · string · required

The album's id, as listPhotoAlbums answers it.

photoId path · string · required

The photo's id, as listPhotos answers it.

If-Match header · string

The ETag the item was read at. When it is sent and the item has changed since, the write is refused with 412.

Answer 204

Make a share link for an album

operationId sharePhotoAlbum · App password · scopes photos:write

Makes a gallery link to the album anybody who has it can open, until it expires or is revoked: by default for 7 days, without EXIF and GPS, showing the edits. With proofing, the visitor can pick photos and approve the set. An organisation's rules may require a password or an expiry.

Parameters

albumId path · string · required

The album's id, as listPhotoAlbums answers it.

Idempotency-Key header · string

Any unique string up to 255 characters. A POST retried with the same key and body within 24 hours answers what the first one did, without doing it again.

Request body application/json

expiresIn "1h" | "1d" | "7d" | "30d" | "never"

How long the link lasts: 1h, 1d, 7d, 30d or never. 7d when absent.

password string

A password the visitor must type, at least 8 characters. Absent or empty for none.

allowDownload boolean

Whether the visitor may download the photos. true when absent.

stripMetadata boolean

Remove EXIF, and with it any GPS position, from what the link serves. true when absent.

variant "edited" | "original"

Serve the edited photo or the untouched original. edited when absent.

proofing boolean

Let the visitor pick photos, note them and approve the set.

Answer 201 application/json

share object · required

—

List the library's share links

operationId listPhotoShares · App password · scopes photos:read

Returns the links made for photos, albums and Photos folders, newest first, expired and revoked ones included so you can confirm a link is dead; the newest 200, as in the app. Each carries its URL, which is the capability: do not pass it on.

Parameters

cursor query · string

The nextCursor of the previous page. Absent for the first.

limit query · integer

How many items to return.

Answer 200 application/json

shares object[] · required

—

nextCursor string | null · required

Pass as ?cursor= for the next page; null on the last one.

Revoke a share link

operationId revokePhotoShare · App password · scopes photos:write

Stops the link working at once; it stays listed as revoked. A thumbnail URL the link already handed out lasts at most another minute. Only Photos' links: a board's or a document's link is not found here.

Parameters

shareId path · string · required

The link's id, as listPhotoShares answers it.

If-Match header · string

The ETag the item was read at. When it is sent and the item has changed since, the write is refused with 412.

Answer 204

List the Code projects this account is on

operationId listCodeProjects · App password · scopes code:read

Returns the projects the account owns or is a member of, most recently changed first, with its role on each. A project is a Drive folder; its id is the folder's. listCodeTree lists one's files.

Parameters

cursor query · string

The nextCursor of the previous page. Absent for the first.

limit query · integer

How many items to return.

Answer 200 application/json

projects object[] · required

—

nextCursor string | null · required

Pass as ?cursor= for the next page; null on the last one.

List a project's files and folders

operationId listCodeTree · App password · scopes code:read

Returns every file and folder under the project, by path, with each file's size, version and whether Code edits it as text. prefix narrows it to one folder. Read a file's text with getCodeFile.

Parameters

projectId path · string · required

The project's id, as listCodeProjects answers it.

cursor query · string

The nextCursor of the previous page. Absent for the first.

limit query · integer

How many items to return.

prefix query · string

Only what is inside this folder of the project, such as src. Absent for the whole tree.

Answer 200 application/json

entries object[] · required

—

truncated boolean · required

Whether the project has more entries than the API lists.

nextCursor string | null · required

Pass as ?cursor= for the next page; null on the last one.

Read a file of a project as text

operationId getCodeFile · App password · scopes code:read

Returns the file at path with its whole text, exactly as stored, and its version. The ETag is the version: send it as If-Match when you write the file back with putCodeFile. A file that is not text, or past 2 MB, is refused as unprocessable.

Parameters

projectId path · string · required

The project's id, as listCodeProjects answers it.

path query · string · required

The file's path inside the project, such as src/main.ts.

Answer 200 application/json

file object · required

—

text string · required

—

Write a file's whole text, or make a new file

operationId putCodeFile · App password · scopes code:write

Replaces the text of the file at path, or makes the file — and any folders on its path — when there is none. Overwriting needs If-Match with the version you read (or * for whatever is there): a save made since answers 412 with the version it is at now. The change is in the file's history, marked with the token's name.

Parameters

projectId path · string · required

The project's id, as listCodeProjects answers it.

path query · string · required

The file's path inside the project, such as src/main.ts.

If-Match header · string

The ETag the item was read at. When it is sent and the item has changed since, the write is refused with 412.

Request body application/json

text string · required

The file's whole new text, written byte for byte: line endings and a byte order mark are kept as sent.

Answer 200 application/json

file object · required

—

outcome "saved" | "unchanged" | "created" · required

unchanged: the file already held this text, and nothing was written.

List a project's checkpoints

operationId listCodeCheckpoints · App password · scopes code:read

Returns the project's checkpoints, newest first: named states of its text files that restoreCodeCheckpoint puts back. getCodeCheckpoint compares one with the project as it is now.

Parameters

projectId path · string · required

The project's id, as listCodeProjects answers it.

cursor query · string

The nextCursor of the previous page. Absent for the first.

limit query · integer

How many items to return.

Answer 200 application/json

checkpoints object[] · required

—

nextCursor string | null · required

Pass as ?cursor= for the next page; null on the last one.

Take a checkpoint of a project

operationId createCodeCheckpoint · App password · scopes code:write

Keeps every text file of the project as it is now, under label, without copying a byte. Take one before a change you may want to undo. A project keeps at most 50, and at most 2000 files each; past either it is refused as a conflict.

Parameters

projectId path · string · required

The project's id, as listCodeProjects answers it.

Idempotency-Key header · string

Any unique string up to 255 characters. A POST retried with the same key and body within 24 hours answers what the first one did, without doing it again.

Request body application/json

label string · required

A name for the checkpoint, such as Before the refactor.

Answer 201 application/json

checkpoint object · required

—

Compare a checkpoint with the project now

operationId getCodeCheckpoint · App password · scopes code:read

Returns the checkpoint and, for each file it keeps, whether the project has it the same, changed or deleted now: what restoreCodeCheckpoint would put back. Files made since the checkpoint are not listed; a restore leaves them.

Parameters

projectId path · string · required

The project's id, as listCodeProjects answers it.

checkpointId path · string · required

The checkpoint's id, as listCodeCheckpoints answers it.

Answer 200 application/json

checkpoint object · required

—

files object[] · required

—

counts object · required

—

Put a project's files back as a checkpoint kept them

operationId restoreCodeCheckpoint · App password · scopes code:write

Restores the files that differ from the checkpoint, four a call, in path order: each changed file gets the kept text as a new version, each deleted one is made again. Files made since are left alone. While remaining is above 0, call again with after set to next. Each restore is in the file's history, marked with the token's name.

Parameters

projectId path · string · required

The project's id, as listCodeProjects answers it.

checkpointId path · string · required

The checkpoint's id, as listCodeCheckpoints answers it.

Idempotency-Key header · string

Any unique string up to 255 characters. A POST retried with the same key and body within 24 hours answers what the first one did, without doing it again.

Request body application/json

after string

The next member of the previous answer, to go on from there. Absent for the first call.

Answer 200 application/json

results object[] · required

—

remaining integer · required

Files that still differ after these, to restore with the next call.

next string | null · required

Pass as after for the next call; null when this was the last.

Apply a unified patch to a project, or preview it

operationId applyCodePatch · App password · scopes code:write

Applies a git diff or diff -u to the project's files: each hunk must find its lines in the file exactly, near where it says, and is never forced. Send dryRun true first to see each file's diff and any hunk that does not apply. Without it, the patch is written only when every file applies whole, else it is refused as a conflict and nothing is written. At most four files a patch; deleting and renaming are not done.

Parameters

projectId path · string · required

The project's id, as listCodeProjects answers it.

Idempotency-Key header · string

Any unique string up to 255 characters. A POST retried with the same key and body within 24 hours answers what the first one did, without doing it again.

Request body application/json

patch string · required

A unified diff, as git diff or diff -u writes it. Paths may carry git's a/ and b/.

dryRun boolean

true to answer what the patch would do, with each file's diff, and write nothing.

Answer 200 application/json

dryRun boolean · required

—

applied boolean · required

Whether every file was written. Always false on a dry run.

files object[] · required

—

List the drives this account can work in

operationId listDriveTrees · App password · scopes drive:read

Returns your own Drive, your own files in each organisation you belong to, and each shared drive you can open, with your role in each. Every other Drive operation works in your own Drive unless it is sent the org (and drive) this answers. Start here when the files you want are an organisation's.

Answer 200 application/json

trees object[] · required

—

List what is in a folder

operationId listDriveFolder · App password · scopes drive:read

Returns one page of a folder's files and folders, folders first, without their bytes. Use root for the top of the tree. For a token limited to one folder, root is that folder. Use searchDrive to find something by name anywhere below.

Parameters

folderId path · string · required

A folder's id, or root for the top of the tree.

cursor query · string

The nextCursor of the previous page. Absent for the first.

limit query · integer

How many items to return.

org query · string

An organisation's slug, as listDriveTrees answers it, to work in its files instead of your own Drive. Alone it is your own space there (My files).

drive query · string

With org: one of its shared drives, by the id listDriveTrees answers.

sort query · "name" | "size" | "modified" | "type"

What to order by; folders always come first. name when absent.

order query · "asc" | "desc"

asc when absent.

Answer 200 application/json

folder object | null · required

—

items object[] · required

—

nextCursor string | null · required

Pass as ?cursor= for the next page; null on the last one.

Make a folder

operationId createDriveFolder · App password · scopes drive:write

Makes a folder inside parentId, or at the top of the tree for null — for a token limited to one folder, inside that folder. A name the folder already holds becomes name (2); the answer says which name it got. Needs Contributor or better in an organisation's drive.

Parameters

org query · string

An organisation's slug, as listDriveTrees answers it, to work in its files instead of your own Drive. Alone it is your own space there (My files).

drive query · string

With org: one of its shared drives, by the id listDriveTrees answers.

Idempotency-Key header · string

Any unique string up to 255 characters. A POST retried with the same key and body within 24 hours answers what the first one did, without doing it again.

Request body application/json

parentId string | null · required

The folder to make it in, or null for the top of the tree.

name string · required

The folder's name. A name the folder already holds becomes name (2).

Answer 201 application/json

node object · required

—

Upload a file into a folder

operationId uploadDriveFile · App password · scopes drive:write

Stores the request body as a file called name in the folder (root for the top of the tree). Send the bytes as they are, with their Content-Type, at most 24 MB; for larger files use WebDAV. Storage cannot take an upload from a signed URL, so the bytes come here, once. Send sha256 to have them checked before anything is stored; it is required with an Idempotency-Key, which keeps a retry from storing them twice.

Parameters

folderId path · string · required

A folder's id, or root for the top of the tree.

org query · string

An organisation's slug, as listDriveTrees answers it, to work in its files instead of your own Drive. Alone it is your own space there (My files).

drive query · string

With org: one of its shared drives, by the id listDriveTrees answers.

name query · string · required

The file's name, with its extension.

conflict query · "rename" | "replace"

When the folder already holds the name: rename stores this one as name (2), replace puts the old file in the bin and takes its name. rename when absent.

sha256 query · string

The SHA-256 of the bytes, in hex. When sent, bytes that do not match are refused with 422 and nothing is stored.

Idempotency-Key header · string

Any unique string up to 255 characters. A POST retried with the same key and body within 24 hours answers what the first one did, without doing it again.

Request body application/octet-stream

Answer 201 application/json

node object · required

—

status "stored" | "replaced" · required

replaced when it took the name of a file that is now in the bin.

Find files and folders by name

operationId searchDrive · App password · scopes drive:read

Returns the files and folders whose name contains q, in the whole tree or below folderId, folders first. Only names are searched, not what is inside the files. The bin is not searched: listDriveTrash lists it.

Parameters

cursor query · string

The nextCursor of the previous page. Absent for the first.

limit query · integer

How many items to return.

org query · string

An organisation's slug, as listDriveTrees answers it, to work in its files instead of your own Drive. Alone it is your own space there (My files).

drive query · string

With org: one of its shared drives, by the id listDriveTrees answers.

q query · string · required

Part of the name to look for, in any case.

folderId query · string

Only look in this folder and the folders under it. The whole tree when absent.

kind query · "folder" | "file" | "photo" | "video" | "doc" | "sheet" | "painting" | "slides" | "dataview"

Only this kind of item.

Answer 200 application/json

items object[] · required

—

nextCursor string | null · required

Pass as ?cursor= for the next page; null on the last one.

Read a file's or folder's details

operationId getDriveNode · App password · scopes drive:read

Returns one file or folder: its name, where it is, its size, type and hash, and whether a token made it. The ETag changes with any of them; send it as If-Match to updateDriveNode or trashDriveNode to act only on what you read. For the bytes, use getDriveDownload.

Parameters

nodeId path · string · required

The file's or folder's id, as listDriveFolder or searchDrive answers it.

org query · string

An organisation's slug, as listDriveTrees answers it, to work in its files instead of your own Drive. Alone it is your own space there (My files).

drive query · string

With org: one of its shared drives, by the id listDriveTrees answers.

Answer 200 application/json

node object · required

—

Rename or move a file or folder

operationId updateDriveNode · App password · scopes drive:write

Renames it (name), moves it into another folder (parentId, null for the top of the tree), or both. A name the destination already holds becomes name (2); the answer says which. A folder cannot go inside itself. In an organisation's drive a Contributor may only change what they added.

Parameters

nodeId path · string · required

The file's or folder's id, as listDriveFolder or searchDrive answers it.

org query · string

An organisation's slug, as listDriveTrees answers it, to work in its files instead of your own Drive. Alone it is your own space there (My files).

drive query · string

With org: one of its shared drives, by the id listDriveTrees answers.

If-Match header · string

The ETag the item was read at. When it is sent and the item has changed since, the write is refused with 412.

Request body application/json

name string

A new name. A name the folder already holds becomes name (2).

parentId string | null

Move it into this folder, or null for the top of the tree.

Answer 200 application/json

node object · required

—

Move a file or folder to the bin

operationId trashDriveNode · App password · scopes drive:write

Moves it, and everything in a folder, to the bin, where restoreDriveNode brings it back to where it was. Nothing is deleted for good through the API. In an organisation's drive a Contributor may only bin what they added.

Parameters

nodeId path · string · required

The file's or folder's id, as listDriveFolder or searchDrive answers it.

org query · string

An organisation's slug, as listDriveTrees answers it, to work in its files instead of your own Drive. Alone it is your own space there (My files).

drive query · string

With org: one of its shared drives, by the id listDriveTrees answers.

If-Match header · string

The ETag the item was read at. When it is sent and the item has changed since, the write is refused with 412.

Answer 204

Bring a file or folder back from the bin

operationId restoreDriveNode · App password · scopes drive:write

Puts an item from the bin back in the folder it was binned from, or at the top of the tree when that folder is gone too. A name taken since becomes name (2). In an organisation's drive this needs a Content manager.

Parameters

nodeId path · string · required

The binned item's id, as listDriveTrash answers it.

org query · string

An organisation's slug, as listDriveTrees answers it, to work in its files instead of your own Drive. Alone it is your own space there (My files).

drive query · string

With org: one of its shared drives, by the id listDriveTrees answers.

Idempotency-Key header · string

Any unique string up to 255 characters. A POST retried with the same key and body within 24 hours answers what the first one did, without doing it again.

Answer 200 application/json

node object · required

—

List what is in the bin

operationId listDriveTrash · App password · scopes drive:read

Returns the files and folders that were moved to the bin, newest first — each as it was binned, not what was inside a binned folder. restoreDriveNode brings one back.

Parameters

cursor query · string

The nextCursor of the previous page. Absent for the first.

limit query · integer

How many items to return.

org query · string

An organisation's slug, as listDriveTrees answers it, to work in its files instead of your own Drive. Alone it is your own space there (My files).

drive query · string

With org: one of its shared drives, by the id listDriveTrees answers.

Answer 200 application/json

items object[] · required

—

nextCursor string | null · required

Pass as ?cursor= for the next page; null on the last one.

List a file's versions

operationId listDriveVersions · App password · scopes drive:read

Returns the versions a file keeps, newest first. A text file edited in Code keeps its past versions; any other file has one, its bytes now — replacing it by upload puts the old file in the bin instead. getDriveDownload with ?version= fetches any of them.

Parameters

nodeId path · string · required

The file's or folder's id, as listDriveFolder or searchDrive answers it.

cursor query · string

The nextCursor of the previous page. Absent for the first.

limit query · integer

How many items to return.

org query · string

An organisation's slug, as listDriveTrees answers it, to work in its files instead of your own Drive. Alone it is your own space there (My files).

drive query · string

With org: one of its shared drives, by the id listDriveTrees answers.

Answer 200 application/json

versions object[] · required

—

nextCursor string | null · required

Pass as ?cursor= for the next page; null on the last one.

Get a short-lived URL for a file's bytes

operationId getDriveDownload · App password · scopes drive:read

Returns where to fetch a file's bytes — now, or a past version's with ?version= — rather than the bytes: a signed storage URL that works for five minutes without the token. Where storage cannot sign, the url is getDriveContent's path on this host, fetched with the token. A folder has no bytes and answers 409.

Parameters

nodeId path · string · required

The file's or folder's id, as listDriveFolder or searchDrive answers it.

org query · string

An organisation's slug, as listDriveTrees answers it, to work in its files instead of your own Drive. Alone it is your own space there (My files).

drive query · string

With org: one of its shared drives, by the id listDriveTrees answers.

version query · number

A past version, as listDriveVersions numbers them. The current bytes when absent.

Answer 200 application/json

download object · required

—

Fetch a file's bytes

operationId getDriveContent · App password · scopes drive:read

Answers a file's bytes, or a past version's with ?version=. Where storage can sign a URL this is a 303 to it, so the bytes never pass through here; only where it cannot are they streamed. Prefer getDriveDownload, which says which.

Parameters

nodeId path · string · required

The file's or folder's id, as listDriveFolder or searchDrive answers it.

org query · string

An organisation's slug, as listDriveTrees answers it, to work in its files instead of your own Drive. Alone it is your own space there (My files).

drive query · string

With org: one of its shared drives, by the id listDriveTrees answers.

version query · number

A past version, as listDriveVersions numbers them. The current bytes when absent.

Answer 200 application/octet-stream

List a file's share links

operationId listDriveShares · App password · scopes drive:read

Returns the links made for one file, newest first, including revoked and expired ones, so you can confirm a link is dead. In an organisation's drive this needs a Content manager.

Parameters

nodeId path · string · required

The file's or folder's id, as listDriveFolder or searchDrive answers it.

cursor query · string

The nextCursor of the previous page. Absent for the first.

limit query · integer

How many items to return.

org query · string

An organisation's slug, as listDriveTrees answers it, to work in its files instead of your own Drive. Alone it is your own space there (My files).

drive query · string

With org: one of its shared drives, by the id listDriveTrees answers.

Answer 200 application/json

shares object[] · required

—

nextCursor string | null · required

Pass as ?cursor= for the next page; null on the last one.

Make a share link for a file

operationId createDriveShare · App password · scopes drive:write

Makes a link anybody who has it can open the file with, until it expires or revokeDriveShare withdraws it: share only what you were asked to. A week unless duration says otherwise. Folders cannot be shared by link. An organisation's rules may require a password and an expiry, or allow no links at all; in its drives this needs a Content manager.

Parameters

nodeId path · string · required

The file's or folder's id, as listDriveFolder or searchDrive answers it.

org query · string

An organisation's slug, as listDriveTrees answers it, to work in its files instead of your own Drive. Alone it is your own space there (My files).

drive query · string

With org: one of its shared drives, by the id listDriveTrees answers.

Idempotency-Key header · string

Any unique string up to 255 characters. A POST retried with the same key and body within 24 hours answers what the first one did, without doing it again.

Request body application/json

duration "1h" | "1d" | "7d" | "30d" | "never"

How long the link works: 1h, 1d, 7d, 30d or never. 7d when absent.

password string

A password the visitor must also give, at least 8 characters. None when absent or empty.

allowDownload boolean

Whether the visitor may download the file. true when absent.

stripMetadata boolean

For a photo: take EXIF and location out of what the visitor gets. true when absent.

Answer 201 application/json

share object · required

—

Revoke a share link

operationId revokeDriveShare · App password · scopes drive:write

Stops a link from working, at once. The link stays in listDriveShares as revoked. Revoking a revoked link changes nothing. In an organisation's drive this needs a Content manager.

Parameters

shareId path · string · required

The link's id, as listDriveShares or createDriveShare answers it.

org query · string

An organisation's slug, as listDriveTrees answers it, to work in its files instead of your own Drive. Alone it is your own space there (My files).

drive query · string

With org: one of its shared drives, by the id listDriveTrees answers.

If-Match header · string

The ETag the item was read at. When it is sent and the item has changed since, the write is refused with 412.

Answer 204

List what changed in a Drive since a cursor

operationId listDriveChanges · App password · scopes drive:read

Returns the folders and files of the tree that changed after cursor, oldest first, up to 500 at a time, with a new cursor; while more is true, ask again at once. A deletion — to the bin or for good — is a change with deleted true. A rename or a move changes only the node moved: keep the tree by id and parentId to know where the files under a folder went. Documents and the other items an app keeps as rows are not listed. A cursor older than the feed remembers deletions answers 410: start again without one. For a program that keeps a copy, such as a synced folder; a token limited to one folder cannot use it.

Parameters

org query · string

An organisation's slug, as listDriveTrees answers it, to work in its files instead of your own Drive. Alone it is your own space there (My files).

drive query · string

With org: one of its shared drives, by the id listDriveTrees answers.

cursor query · string

The cursor the previous answer gave. Absent or empty for everything.

Answer 200 application/json

changes object[] · required

—

cursor string · required

Send as ?cursor= next time. Empty while the tree has never changed.

more boolean · required

More changes are waiting: ask again now.

Say how much storage the tree uses and has

operationId getDriveQuota · App password · scopes drive:read

Returns the bytes the tree's owner stores — their files, the bin and past versions — and the most they may store. In an organisation it is the drive's or your space's owner whose storage this is.

Parameters

org query · string

An organisation's slug, as listDriveTrees answers it, to work in its files instead of your own Drive. Alone it is your own space there (My files).

drive query · string

With org: one of its shared drives, by the id listDriveTrees answers.

Answer 200 application/json

used number · required

Bytes stored now.

total number · required

The most bytes that may be stored.

Look up a file by its path and get its bytes' URL

operationId getDriveFile · App password · scopes drive:read

Returns the file at path as listDriveChanges describes it, with its revision as the ETag, and where to fetch its bytes: a signed storage URL that works for five minutes without the token, or getDriveContent's path on this host where storage cannot sign. A folder, or a document an app keeps as rows, is not found.

Parameters

org query · string

An organisation's slug, as listDriveTrees answers it, to work in its files instead of your own Drive. Alone it is your own space there (My files).

drive query · string

With org: one of its shared drives, by the id listDriveTrees answers.

path query · string · required

The file's path from the top of the tree, such as Projects/Plan.odt.

Answer 200 application/json

file object · required

—

download object · required

—

Write a file at a path, against the revision it was based on

operationId putDriveFile · App password · scopes drive:write

Stores the body as the file at path, making the folders above it that are missing. Send If-Match with the revision the change was based on, or If-None-Match: * for a file that must not exist yet; if the file has moved on since, nothing is written and the 412 carries the file as it is now in its file member. Writing over a file puts the old one in the bin and the new one has a new id. At most 24 MB; a note, wiki page, Code file, SQL database or edited PDF is changed in its app and answers 409.

Parameters

org query · string

An organisation's slug, as listDriveTrees answers it, to work in its files instead of your own Drive. Alone it is your own space there (My files).

drive query · string

With org: one of its shared drives, by the id listDriveTrees answers.

path query · string · required

The file's path from the top of the tree, such as Projects/Plan.odt.

sha256 query · string

The bytes' SHA-256 in hex. Sent, the bytes are checked against it before anything is stored.

If-Match header · string

The revision the change was based on, as an ETag. A file at path with another revision is not written over (412).

If-None-Match header · string

* when the file must not exist yet. Either this or If-Match is required (428).

Request body application/octet-stream

Answer 200 application/json

file object · required

—

Move a file at a path to the bin, against its revision

operationId deleteDriveFile · App password · scopes drive:write

Moves the file at path to the bin if it is still at the revision in If-Match; if it has moved on since, nothing happens and the 412 carries the file as it is now in its file member. A path where nothing is answers 204 too. A folder is not deleted this way (409).

Parameters

org query · string

An organisation's slug, as listDriveTrees answers it, to work in its files instead of your own Drive. Alone it is your own space there (My files).

drive query · string

With org: one of its shared drives, by the id listDriveTrees answers.

path query · string · required

The file's path from the top of the tree, such as Projects/Plan.odt.

If-Match header · string · required

The ETag the item was read at. Required: without it the answer is 428, and with a stale one 412.

Answer 204

List the SQLite databases this account can open

operationId listSqlDatabases · App password · scopes sql:read

Returns the account's own databases — every .sqlite, .sqlite3 and .db file in its Drive — then those shared with it, then those in its organisations' shared drives and its member spaces, with its role on each, the organisation and drive each is in, and the version a write is guarded on. Start here to find a database's id.

Parameters

cursor query · string

The nextCursor of the previous page. Absent for the first.

limit query · integer

How many items to return.

Answer 200 application/json

databases object[] · required

—

nextCursor string | null · required

Pass as ?cursor= for the next page; null on the last one.

List a database's tables and views with their columns

operationId listSqlTables · App password · scopes sql:read

Returns every table and view of the database with its columns — declared type, NOT NULL, primary key, default — and the CREATE statement that made it. Read this before writing a query. The ETag is the database's version. The API opens databases up to 32 MB; a larger one answers unprocessable and is read in the SQL app.

Parameters

databaseId path · string · required

The database's id, as listSqlDatabases answers it.

Answer 200 application/json

version integer · required

Goes up with every save of the file. The ETag is this number in quotes.

tables object[] · required

—

Run a query that reads, with parameters

operationId runSqlQuery · App password · scopes sql:read

Runs one statement that reads — SELECT, WITH, or a PRAGMA that describes — with its parameters bound, and returns a page of its rows. A statement that would change the database is refused with read-only before it runs, whatever scopes the token has: writes go to runSqlStatement. Each page re-runs the query against the same version; if the database was saved in between, the cursor answers conflict. A statement may run for 3 seconds.

Parameters

databaseId path · string · required

The database's id, as listSqlDatabases answers it.

cursor query · string

The nextCursor of the previous page. Absent for the first.

limit query · integer

How many items to return.

Request body application/json

sql string · required

One statement that reads: a SELECT, a WITH … SELECT, or a PRAGMA that describes.

params string | number | boolean | null | object[] | { [key]: string | number | boolean | null | object }

Values for the SQL's parameters. An object names each one as the SQL does (":year", "@who", "?2") or without its sigil ("year"); an array fills ? and ?1, ?2… in order. Every parameter needs a value, and every value a parameter. A boolean binds 1 or 0.

Answer 200 application/json

columns object[] · required

—

rows string | number | null | object[][] · required

One array per row, its values in the order of columns.

version integer · required

The version of the database the rows were read from.

nextCursor string | null · required

Pass as ?cursor= for the next page; null on the last one.

Run statements that write, as one transaction

operationId runSqlStatement · App password · scopes sql:write

Runs one or more statements that change the database — INSERT, UPDATE, DELETE, CREATE, ALTER, DROP — bound from one set of parameters, all or nothing, and saves the file as a new version in its history, marked with the token's name. Rows a RETURNING clause gives back are answered, up to 1000. Needs the editor role. If-Match with the version you read refuses to write over a save made since. The API writes databases up to 16 MB, and a script may run for 3 seconds.

Parameters

databaseId path · string · required

The database's id, as listSqlDatabases answers it.

If-Match header · string

The ETag the item was read at. When it is sent and the item has changed since, the write is refused with 412.

Idempotency-Key header · string

Any unique string up to 255 characters. A POST retried with the same key and body within 24 hours answers what the first one did, without doing it again.

Request body application/json

sql string · required

One statement or several, separated by semicolons: INSERT, UPDATE, DELETE, CREATE, ALTER, DROP. They run in order as one transaction, and the first that fails undoes the rest.

params string | number | boolean | null | object[] | { [key]: string | number | boolean | null | object }

Values for the SQL's parameters. An object names each one as the SQL does (":year", "@who", "?2") or without its sigil ("year"); an array fills ? and ?1, ?2… in order. Every parameter needs a value, and every value a parameter. A boolean binds 1 or 0.

Answer 200 application/json

saved boolean · required

False when the statements changed nothing, and no version was made.

version integer · required

Goes up with every save of the file. The ETag is this number in quotes.

statements object[] · required

—

List the queries saved on a database

operationId listSqlSavedQueries · App password · scopes sql:read

Returns the queries this account saved on the database in the SQL app, by name, with their SQL and the parameters each names. Run one with runSqlSavedQuery.

Parameters

databaseId path · string · required

The database's id, as listSqlDatabases answers it.

cursor query · string

The nextCursor of the previous page. Absent for the first.

limit query · integer

How many items to return.

Answer 200 application/json

queries object[] · required

—

nextCursor string | null · required

Pass as ?cursor= for the next page; null on the last one.

Run a saved query, with parameters

operationId runSqlSavedQuery · App password · scopes sql:read

Runs a query saved in the SQL app exactly as runSqlQuery runs SQL: it reads, and a saved statement that would write is refused with read-only. Give values for the parameters listSqlSavedQueries names. Pages the same way.

Parameters

databaseId path · string · required

The database's id, as listSqlDatabases answers it.

queryId path · string · required

The saved query's id, as listSqlSavedQueries answers it.

cursor query · string

The nextCursor of the previous page. Absent for the first.

limit query · integer

How many items to return.

Request body application/json

params string | number | boolean | null | object[] | { [key]: string | number | boolean | null | object }

Values for the SQL's parameters. An object names each one as the SQL does (":year", "@who", "?2") or without its sigil ("year"); an array fills ? and ?1, ?2… in order. Every parameter needs a value, and every value a parameter. A boolean binds 1 or 0.

Answer 200 application/json

columns object[] · required

—

rows string | number | null | object[][] · required

One array per row, its values in the order of columns.

version integer · required

The version of the database the rows were read from.

nextCursor string | null · required

Pass as ?cursor= for the next page; null on the last one.

List the PDFs this account can open

operationId listPdfs · App password · scopes pdf:read

Returns the PDFs in the account's own Drive and those shared with it, most recently changed first, with the role on each and whether it has been edited. Start here to find a file's id. q narrows by name.

Parameters

cursor query · string

The nextCursor of the previous page. Absent for the first.

limit query · integer

How many items to return.

q query · string

Only files whose name contains this.

Answer 200 application/json

files object[] · required

—

nextCursor string | null · required

Pass as ?cursor= for the next page; null on the last one.

Read a PDF's metadata and pages

operationId getPdf · App password · scopes pdf:read

Returns one PDF as it is served — with its edits from the PDF app — and what the file says about itself: its page count and each page's size and rotation, its title, author and dates, and how many form fields, attachments and bookmarks it has. Files of up to 20 MB, the inputs of one request together; a larger one is file-too-large.

Parameters

fileId path · string · required

The PDF's id, as listPdfs answers it.

Answer 200 application/json

file object · required

—

document object · required

—

List a PDF's form fields and their values

operationId listPdfFormFields · App password · scopes pdf:read

Returns every field of the PDF's form, as it is served: its full name, its kind, what it holds now, its options, whether it is read-only or required, and the pages it is on. The names and option values are what fillPdfForm takes. A file without a form answers an empty list. Files of up to 20 MB, the inputs of one request together; a larger one is file-too-large.

Parameters

fileId path · string · required

The PDF's id, as listPdfs answers it.

Answer 200 application/json

fields object[] · required

—

Get a short-lived link to a PDF's bytes

operationId getPdfDownload · App password · scopes pdf:read

Returns a URL the file can be fetched from without a credential, valid until expiresAt — fetch it, do not store it. The file as served, with its edits; original=true for the file as it was uploaded. Where no signed link can be made, url is the path of downloadPdf, which takes the same credential as this call and answers the bytes itself, and expiresAt is null.

Parameters

fileId path · string · required

The PDF's id, as listPdfs answers it.

original query · "true" | "false"

true for the file as uploaded, before any edit in the PDF app.

Answer 200 application/json

url string · required

—

expiresAt string (date-time) | null · required

—

name string · required

—

size number · required

—

contentType "application/pdf" · required

—

edition "edited" | "original" · required

Which one the URL hands out.

Download a PDF's bytes through the API

operationId downloadPdf · App password · scopes pdf:read

Answers the file's bytes, streamed — as served with its edits, or original=true for the file as uploaded. Prefer getPdfDownload, whose link does not pass the bytes through the API; this is where its url points when no signed link can be made.

Parameters

fileId path · string · required

The PDF's id, as listPdfs answers it.

original query · "true" | "false"

true for the file as uploaded, before any edit in the PDF app.

Answer 200 application/pdf

Turn a PDF's pages into a new file

operationId rotatePdf · App password · scopes pdf:write

Writes a new PDF in your Drive: the file as served, with every page — or the pages named — turned clockwise. The file itself is not changed. Its form, markup, links and bookmarks come along. Files of up to 20 MB, the inputs of one request together; a larger one is file-too-large.

Parameters

fileId path · string · required

The PDF's id, as listPdfs answers it.

Idempotency-Key header · string

Any unique string up to 255 characters. A POST retried with the same key and body within 24 hours answers what the first one did, without doing it again.

Request body application/json

degrees 90 | 180 | 270 · required

Clockwise, on top of how each page is turned now.

pages integer[]

The pages to turn, from 1. Absent turns every page.

name string

The new file's name. Absent names it after the file it came from.

folderId string

A folder of your own Drive to put the new file in. Absent puts it beside the file it came from when that file is yours, and in your Drive's top level otherwise.

Answer 201 application/json

file object · required

—

Reorder, drop, duplicate or turn pages into a new file

operationId rearrangePdfPages · App password · scopes pdf:write

Writes a new PDF in your Drive whose pages are the list given, in that order, each a page of the file as served with an optional turn: a page left out is dropped, one named twice appears twice. The file itself is not changed; what is on the pages kept comes along, and bookmarks follow their pages. Files of up to 20 MB, the inputs of one request together; a larger one is file-too-large.

Parameters

fileId path · string · required

The PDF's id, as listPdfs answers it.

Idempotency-Key header · string

Any unique string up to 255 characters. A POST retried with the same key and body within 24 hours answers what the first one did, without doing it again.

Request body application/json

pages object[] · required

The new file's pages, in order. A page left out is dropped and a page named twice appears twice: reorder, delete and duplicate are all this list.

name string

The new file's name. Absent names it after the file it came from.

folderId string

A folder of your own Drive to put the new file in. Absent puts it beside the file it came from when that file is yours, and in your Drive's top level otherwise.

Answer 201 application/json

file object · required

—

Split a PDF into new files by page ranges

operationId splitPdf · App password · scopes pdf:write

Writes one new PDF in your Drive per part — page ranges, or a new part every N pages — each named after the file and its pages. At most 20 parts. The file itself is not changed. Parts are stored one at a time: if one cannot be (storage-full), the refusal's files member names the parts already stored. Files of up to 20 MB, the inputs of one request together; a larger one is file-too-large.

Parameters

fileId path · string · required

The PDF's id, as listPdfs answers it.

Idempotency-Key header · string

Any unique string up to 255 characters. A POST retried with the same key and body within 24 hours answers what the first one did, without doing it again.

Request body application/json

ranges object[]

Each part as a range of pages, from 1, both ends included. Ranges may overlap.

every integer

Or: a new part every this many pages.

folderId string

A folder of your own Drive to put the new file in. Absent puts it beside the file it came from when that file is yours, and in your Drive's top level otherwise.

Answer 201 application/json

files object[] · required

—

Fill a PDF's form into a new file

operationId fillPdfForm · App password · scopes pdf:write

Writes a new PDF in your Drive with the form filled: each value is written with an appearance every reader shows. A field that does not exist, is read-only, or is given the wrong kind of value is refused with invalid-request, never skipped. A signature field is signed in the PDF app and refused here with requires-app. flatten draws the values into the pages. Files of up to 20 MB, the inputs of one request together; a larger one is file-too-large.

Parameters

fileId path · string · required

The PDF's id, as listPdfs answers it.

Idempotency-Key header · string

Any unique string up to 255 characters. A POST retried with the same key and body within 24 hours answers what the first one did, without doing it again.

Request body application/json

values { [key]: string | boolean | string[] } · required

Field name to value, as listPdfFormFields names them: a string for text, true or false for a checkbox, the chosen button's name for a radio group, an option or a list of options for a choice. Fields not named keep their value.

flatten boolean

Draw the values into the pages and leave no form behind, so nobody can change them in a reader.

name string

The new file's name. Absent names it after the file it came from.

folderId string

A folder of your own Drive to put the new file in. Absent puts it beside the file it came from when that file is yours, and in your Drive's top level otherwise.

Answer 201 application/json

file object · required

—

Merge PDFs into a new file

operationId mergePdfs · App password · scopes pdf:write

Writes a new PDF in your Drive made of the files given, in order — all of each, or the pages named. Pages are copied as they are, edits included. As in the PDF app, the files' forms do not come along: a form belongs to one file. Up to 20 files. Files of up to 20 MB, the inputs of one request together; a larger one is file-too-large.

Parameters

Idempotency-Key header · string

Any unique string up to 255 characters. A POST retried with the same key and body within 24 hours answers what the first one did, without doing it again.

Request body application/json

files object[] · required

The files, in the order their pages go into the new one. A file may be named more than once.

name string · required

The new file's name.

folderId string

A folder of your own Drive to put the new file in. Absent puts it beside the file it came from when that file is yours, and in your Drive's top level otherwise.

Answer 201 application/json

file object · required

—

List the decks this account can open

operationId listDecks · App password · scopes slides:read

Returns the account's own presentations and those shared with it, most recently changed first, with the role on each and how many slides it has. q narrows by name or by the words on its slides. Start here to find a deck's id.

Parameters

cursor query · string

The nextCursor of the previous page. Absent for the first.

limit query · integer

How many items to return.

q query · string

Only decks whose name or text contains this.

Answer 200 application/json

decks object[] · required

—

nextCursor string | null · required

Pass as ?cursor= for the next page; null on the last one.

Make a deck from Markdown or from the editor's JSON

operationId createDeck · App password · scopes slides:write

Makes a presentation in your Drive and answers it as getDeck does. Send markdown — one slide per stretch between lines of ---, the first heading on each its title — or body, the editor's JSON; neither makes one empty title slide. Pictures in Markdown are left out: a slide's picture is one of your own files, placed by its id.

Parameters

Idempotency-Key header · string

Any unique string up to 255 characters. A POST retried with the same key and body within 24 hours answers what the first one did, without doing it again.

Request body application/json

name string

The deck's name. Left out, it is the Markdown's first heading.

folderId string

A folder of your own Drive to make it in. Left out, the top of your Drive.

markdown string

Markdown, one slide per stretch between lines of ---. The first heading on a slide is its title; an HTML comment, or everything after a line starting Notes:, is its speaker notes. Pictures in it are left out.

body object

The deck in the editor's JSON: root holds the theme, the size and the slides, as getDeck answers it.

Answer 201 application/json

deck object · required

—

Read a deck with its outline and body

operationId getDeck · App password · scopes slides:read

Returns one presentation: its outline — each slide's id, number, title and layout — and its body, the editor's JSON with every slide and every box on it. The version is the ETag, which every write needs as If-Match. For one slide's text, getSlide is smaller.

Parameters

deckId path · string · required

The deck's id, as listDecks answers it.

Answer 200 application/json

deck object · required

—

Replace a deck's body

operationId replaceDeck · App password · scopes slides:write

Saves a whole new body for the deck through the editor's guarded save, against the version in If-Match, which is required; a deck changed since answers 412 with its version. People editing it in the app see it replaced. While someone in the app has changes not yet saved, the answer is 409: retry after a few seconds. Needs the editor role.

Parameters

deckId path · string · required

The deck's id, as listDecks answers it.

If-Match header · string · required

The ETag the item was read at. Required: without it the answer is 428, and with a stale one 412.

Request body application/json

body object · required

The deck in the editor's JSON: root holds the theme, the size and the slides, as getDeck answers it.

Answer 200 application/json

status "saved" · required

—

version integer · required

Goes up with every change. The ETag is this number in quotes.

slides object[] · required

The deck's outline after the change.

Add slides to a deck

operationId addSlides · App password · scopes slides:write

Inserts slides at position, or after the last one: from markdown, one slide per stretch between lines of ---, or as slides in the editor's JSON. Against the version in If-Match, which is required, as every write to a deck is. Answers the new slides' ids and the deck's outline. Needs the editor role.

Parameters

deckId path · string · required

The deck's id, as listDecks answers it.

If-Match header · string · required

The ETag the item was read at. Required: without it the answer is 428, and with a stale one 412.

Idempotency-Key header · string

Any unique string up to 255 characters. A POST retried with the same key and body within 24 hours answers what the first one did, without doing it again.

Request body application/json

markdown string

Markdown, one slide per stretch between lines of ---. The first heading on a slide is its title; an HTML comment, or everything after a line starting Notes:, is its speaker notes. Pictures in it are left out.

slides object[]

—

position integer

Where the first new slide goes, counting from 1. Left out, after the last slide.

Answer 201 application/json

status "saved" · required

—

version integer · required

Goes up with every change. The ETag is this number in quotes.

slides object[] · required

The deck's outline after the change.

added string[] · required

The new slides' ids, in order.

Read one slide

operationId getSlide · App password · scopes slides:read

Returns one slide: its outline line, its text as Markdown, its speaker notes as Markdown and its body in the editor's JSON. The ETag is the deck's version, which updateSlide and deleteSlide need as If-Match.

Parameters

deckId path · string · required

The deck's id, as listDecks answers it.

slideId path · string · required

The slide's id, as the deck's outline answers it.

Answer 200 application/json

slide object · required

—

version integer · required

Goes up with every change. The ETag is this number in quotes.

Change one slide

operationId updateSlide · App password · scopes slides:write

Changes what the body names and leaves the rest: markdown rewrites the slide's content and notes (it may not be empty: deleteSlide takes a slide out), notes only the notes; hidden, section and transition set those; position moves it; body replaces the slide's JSON keys it names. Against the version in If-Match, which is required. Needs the editor role.

Parameters

deckId path · string · required

The deck's id, as listDecks answers it.

slideId path · string · required

The slide's id, as the deck's outline answers it.

If-Match header · string · required

The ETag the item was read at. Required: without it the answer is 428, and with a stale one 412.

Request body application/json

markdown string

The slide's content and notes, rewritten from Markdown as one slide: its pictures, shapes and charts go with it. The slide keeps its id.

hidden boolean

Kept in the deck and skipped by the show.

section string | null

The section this slide opens, or null for none.

transition "none" | "fade" | "slide" | "zoom" | "morph" | null

How this slide arrives, or null for the deck's own transition.

notes string

The speaker notes, as Markdown; an empty string removes them.

position integer

Move the slide to this number in the deck.

body object

Keys of the slide's JSON to replace — layout, children, notes as blocks and the rest — as getSlide answers them. Its id cannot change.

Answer 200 application/json

status "saved" · required

—

version integer · required

Goes up with every change. The ETag is this number in quotes.

slides object[] · required

The deck's outline after the change.

Delete one slide

operationId deleteSlide · App password · scopes slides:write

Takes the slide out of the deck, against the version in If-Match, which is required. The deck's history keeps it: restoring an earlier version in the app brings it back. Needs the editor role.

Parameters

deckId path · string · required

The deck's id, as listDecks answers it.

slideId path · string · required

The slide's id, as the deck's outline answers it.

If-Match header · string · required

The ETag the item was read at. Required: without it the answer is 428, and with a stale one 412.

Answer 200 application/json

status "saved" · required

—

version integer · required

Goes up with every change. The ETag is this number in quotes.

slides object[] · required

The deck's outline after the change.

Download a deck as Markdown

operationId exportDeckMarkdown · App password · scopes slides:read

Answers the deck as Markdown — one slide per stretch between lines of ---, its notes in HTML comments — as the last save wrote it, which createDeck reads back. The one export offered here: PowerPoint, PDF and pictures are drawn by the Slides app in a browser.

Parameters

deckId path · string · required

The deck's id, as listDecks answers it.

Answer 200 text/markdown

List the calendars this account is on

operationId listCalendars · App password · scopes calendar:read

Returns every calendar the account owns or was given a role on, with that role: busy (it sees only when time is taken), viewer, editor, manager or owner. Start here to find a calendar's id: listEvents reads the ones it is a viewer or more on, listFreeBusy all of them, createEvent writes to the ones it is an editor or more on.

Answer 200 application/json

calendars object[] · required

—

List the events between two days, repeats expanded

operationId listEvents · App password · scopes calendar:read

Returns every instance between from and to — repeating events expanded into their instances, each with its occurrence key — on the calendars the account reads, and the events it is a guest on, soonest first. A private event it may not see is busy time with no title. Busy-only calendars are not here: listFreeBusy answers them. At most 92 days and 1000 instances; complete says whether that bound was reached.

Parameters

from query · string · required

The first day, YYYY-MM-DD.

to query · string · required

The day after the last, YYYY-MM-DD.

zone query · string

The time zone the days are in. Left out, the account's own.

calendarId query · string

Only this calendar's events.

Answer 200 application/json

occurrences object[] · required

—

zone string · required

—

complete boolean · required

False when the range held more than the answer carries: ask for fewer days.

Make an event on a calendar

operationId createEvent · App password · scopes calendar:write

Makes an event — a repeating one with rrule — and answers it as getEvent does. Times are wall times in zone (YYYY-MM-DDTHH:mm) or instants with an offset; an all-day event takes days, the last one included. Without an end it lasts an hour, or one day. Guests named in attendees are invited by email, as from the app. Needs the editor role, on a calendar that is not a subscription.

Parameters

calendarId path · string · required

The calendar's id, as listCalendars answers it.

Idempotency-Key header · string

Any unique string up to 255 characters. A POST retried with the same key and body within 24 hours answers what the first one did, without doing it again.

Request body application/json

summary string · required

The title.

description string | null

—

location string | null

—

url string | null

—

start string · required

A wall time in zone, YYYY-MM-DDTHH:mm, or an instant with its offset (2026-10-05T07:30:00Z). For an all-day event, a day, YYYY-MM-DD; its end is the last day, included.

end string

A wall time in zone, YYYY-MM-DDTHH:mm, or an instant with its offset (2026-10-05T07:30:00Z). For an all-day event, a day, YYYY-MM-DD; its end is the last day, included.

allDay boolean

—

zone string

The IANA time zone the times are in, such as Europe/Berlin. Left out, the account's own.

endZone string | null

—

rrule string | null

—

showAs "busy" | "free"

Whether it counts as busy time. Left out, busy.

visibility "default" | "private"

private shows it as busy time to everyone on the calendar but its owner, whoever made it and its guests.

status "confirmed" | "tentative" | "cancelled"

—

colour string | null

—

attendees string (email)[]

The guests' email addresses; each is invited, as from the app. On a change, the whole list: left out, the guests stay as they are.

Answer 201 application/json

event object · required

—

Read an event

operationId getEvent · App password · scopes calendar:read

Returns one event — the whole series for a repeating one, with its rule and the instances changed on their own — with its ETag, which updateEvent and deleteEvent need as If-Match. A private event the account may not see answers as busy time with no title, details or guests.

Parameters

eventId path · string · required

The event's id, as listEvents answers it as eventId.

Answer 200 application/json

event object · required

—

Change an event, one instance or the series

operationId updateEvent · App password · scopes calendar:write

Changes the fields the body names and keeps the rest — a new start without an end keeps its length — against the ETag in If-Match, which is required. For a repeating event, occurrence and scope say which instances: only this one, this and the following ones (a new series from it), or all. A private event the account sees as busy may only be moved: start and end, nothing else. Needs the editor role.

Parameters

eventId path · string · required

The event's id, as listEvents answers it as eventId.

occurrence query · string

One instance of a repeating event, as listEvents answers it. Left out, the whole event.

scope query · "this" | "following" | "all"

With occurrence: only this instance, this and the following ones, or all of them. Left out, this one.

If-Match header · string · required

The ETag the item was read at. Required: without it the answer is 428, and with a stale one 412.

Request body application/json

summary string

The title.

description string | null

—

location string | null

—

url string | null

—

start string

A wall time in zone, YYYY-MM-DDTHH:mm, or an instant with its offset (2026-10-05T07:30:00Z). For an all-day event, a day, YYYY-MM-DD; its end is the last day, included.

end string

A wall time in zone, YYYY-MM-DDTHH:mm, or an instant with its offset (2026-10-05T07:30:00Z). For an all-day event, a day, YYYY-MM-DD; its end is the last day, included.

allDay boolean

—

zone string

The IANA time zone the times are in, such as Europe/Berlin. Left out, the account's own.

endZone string | null

—

rrule string | null

—

showAs "busy" | "free"

Whether it counts as busy time. Left out, busy.

visibility "default" | "private"

private shows it as busy time to everyone on the calendar but its owner, whoever made it and its guests.

status "confirmed" | "tentative" | "cancelled"

—

colour string | null

—

attendees string (email)[]

The guests' email addresses; each is invited, as from the app. On a change, the whole list: left out, the guests stay as they are.

Answer 200 application/json

event object · required

—

Delete an event, one instance or the series

operationId deleteEvent · App password · scopes calendar:write

Deletes the event against the ETag in If-Match, which is required. A whole event goes to the calendar's trash for 30 days, where the app restores it; with occurrence and scope, only that instance, or it and the following ones, are taken out of the series. Guests are told, as from the app. Needs the editor role.

Parameters

eventId path · string · required

The event's id, as listEvents answers it as eventId.

occurrence query · string

One instance of a repeating event, as listEvents answers it. Left out, the whole event.

scope query · "this" | "following" | "all"

With occurrence: only this instance, this and the following ones, or all of them. Left out, this one.

If-Match header · string · required

The ETag the item was read at. Required: without it the answer is 428, and with a stale one 412.

Answer 204

List when the account's calendars are busy

operationId listFreeBusy · App password · scopes calendar:read

Returns the busy intervals between two instants on each calendar the account is on — busy-only ones included — and all of them merged. Busy time is a timed event that is not cancelled, not shown as free and not on a calendar marked free; all-day events do not count, as in the app's scheduling. At most 62 days.

Parameters

from query · string (date-time) · required

The start, an ISO 8601 instant.

to query · string (date-time) · required

The end, an ISO 8601 instant.

calendarId query · string

Only this calendar.

Answer 200 application/json

calendars object[] · required

—

busy object[] · required

Every calendar's busy time, merged.

complete boolean · required

False when there was more busy time than one answer reads: ask for a shorter range.