Requests

Request

A single update to apply to a document.

JSON representation
{

  // Union field request can be only one of the following:
  "replaceAllText": {
    object (ReplaceAllTextRequest)
  },
  "insertText": {
    object (InsertTextRequest)
  },
  "updateTextStyle": {
    object (UpdateTextStyleRequest)
  },
  "createParagraphBullets": {
    object (CreateParagraphBulletsRequest)
  },
  "deleteParagraphBullets": {
    object (DeleteParagraphBulletsRequest)
  },
  "createNamedRange": {
    object (CreateNamedRangeRequest)
  },
  "deleteNamedRange": {
    object (DeleteNamedRangeRequest)
  },
  "updateParagraphStyle": {
    object (UpdateParagraphStyleRequest)
  },
  "deleteContentRange": {
    object (DeleteContentRangeRequest)
  },
  "insertInlineImage": {
    object (InsertInlineImageRequest)
  },
  "insertTable": {
    object (InsertTableRequest)
  },
  "insertTableRow": {
    object (InsertTableRowRequest)
  },
  "insertTableColumn": {
    object (InsertTableColumnRequest)
  },
  "deleteTableRow": {
    object (DeleteTableRowRequest)
  },
  "deleteTableColumn": {
    object (DeleteTableColumnRequest)
  },
  "insertPageBreak": {
    object (InsertPageBreakRequest)
  },
  "deletePositionedObject": {
    object (DeletePositionedObjectRequest)
  },
  "updateTableColumnProperties": {
    object (UpdateTableColumnPropertiesRequest)
  },
  "updateTableCellStyle": {
    object (UpdateTableCellStyleRequest)
  },
  "updateTableRowStyle": {
    object (UpdateTableRowStyleRequest)
  },
  "replaceImage": {
    object (ReplaceImageRequest)
  },
  "updateDocumentStyle": {
    object (UpdateDocumentStyleRequest)
  },
  "mergeTableCells": {
    object (MergeTableCellsRequest)
  },
  "unmergeTableCells": {
    object (UnmergeTableCellsRequest)
  },
  "createHeader": {
    object (CreateHeaderRequest)
  },
  "createFooter": {
    object (CreateFooterRequest)
  },
  "createFootnote": {
    object (CreateFootnoteRequest)
  },
  "replaceNamedRangeContent": {
    object (ReplaceNamedRangeContentRequest)
  },
  "updateSectionStyle": {
    object (UpdateSectionStyleRequest)
  },
  "insertSectionBreak": {
    object (InsertSectionBreakRequest)
  },
  "deleteHeader": {
    object (DeleteHeaderRequest)
  },
  "deleteFooter": {
    object (DeleteFooterRequest)
  },
  "pinTableHeaderRows": {
    object (PinTableHeaderRowsRequest)
  }
  // End of list of possible types for union field request.
}
Fields
Union field request. The specific request to apply. Exactly one field is required. request can be only one of the following:
replaceAllText

object (ReplaceAllTextRequest)

Replaces all instances of the specified text.

insertText

object (InsertTextRequest)

Inserts text at the specified location.

updateTextStyle

object (UpdateTextStyleRequest)

Updates the text style at the specified range.

createParagraphBullets

object (CreateParagraphBulletsRequest)

Creates bullets for paragraphs.

deleteParagraphBullets

object (DeleteParagraphBulletsRequest)

Deletes bullets from paragraphs.

createNamedRange

object (CreateNamedRangeRequest)

Creates a named range.

deleteNamedRange

object (DeleteNamedRangeRequest)

Deletes a named range.

updateParagraphStyle

object (UpdateParagraphStyleRequest)

Updates the paragraph style at the specified range.

deleteContentRange

object (DeleteContentRangeRequest)

Deletes content from the document.

insertInlineImage

object (InsertInlineImageRequest)

Inserts an inline image at the specified location.

insertTable

object (InsertTableRequest)

Inserts a table at the specified location.

insertTableRow

object (InsertTableRowRequest)

Inserts an empty row into a table.

insertTableColumn

object (InsertTableColumnRequest)

Inserts an empty column into a table.

deleteTableRow

object (DeleteTableRowRequest)

Deletes a row from a table.

deleteTableColumn

object (DeleteTableColumnRequest)

Deletes a column from a table.

insertPageBreak

object (InsertPageBreakRequest)

Inserts a page break at the specified location.

deletePositionedObject

object (DeletePositionedObjectRequest)

Deletes a positioned object from the document.

updateTableColumnProperties

object (UpdateTableColumnPropertiesRequest)

Updates the properties of columns in a table.

updateTableCellStyle

object (UpdateTableCellStyleRequest)

Updates the style of table cells.

updateTableRowStyle

object (UpdateTableRowStyleRequest)

Updates the row style in a table.

replaceImage

object (ReplaceImageRequest)

Replaces an image in the document.

updateDocumentStyle

object (UpdateDocumentStyleRequest)

Updates the style of the document.

mergeTableCells

object (MergeTableCellsRequest)

Merges cells in a table.

unmergeTableCells

object (UnmergeTableCellsRequest)

Unmerges cells in a table.

createHeader

object (CreateHeaderRequest)

Creates a header.

createFootnote

object (CreateFootnoteRequest)

Creates a footnote.

replaceNamedRangeContent

object (ReplaceNamedRangeContentRequest)

Replaces the content in a named range.

updateSectionStyle

object (UpdateSectionStyleRequest)

Updates the section style of the specified range.

insertSectionBreak

object (InsertSectionBreakRequest)

Inserts a section break at the specified location.

deleteHeader

object (DeleteHeaderRequest)

Deletes a header from the document.

pinTableHeaderRows

object (PinTableHeaderRowsRequest)

Updates the number of pinned header rows in a table.

ReplaceAllTextRequest

Replaces all instances of text matching a criteria with replace text.

JSON representation
{
  "replaceText": string,
  "tabsCriteria": {
    object (TabsCriteria)
  },

  // Union field criteria can be only one of the following:
  "containsText": {
    object (SubstringMatchCriteria)
  }
  // End of list of possible types for union field criteria.
}
Fields
replaceText

string

The text that will replace the matched text.

tabsCriteria

object (TabsCriteria)

Optional. The criteria used to specify in which tabs the replacement occurs.

When omitted, the replacement applies to all tabs.

In a document containing a single tab:

  • If provided, must match the singular tab's ID.

  • If omitted, the replacement applies to the singular tab.

In a document containing multiple tabs:

  • If provided, the replacement applies to the specified tabs.

  • If omitted, the replacement applies to all tabs.

Union field criteria. The criteria used to match the text to replace. criteria can be only one of the following:
containsText

object (SubstringMatchCriteria)

Finds text in the document matching this substring.

SubstringMatchCriteria

A criteria that matches a specific string of text in the document.

JSON representation
{
  "text": string,
  "matchCase": boolean
}
Fields
text

string

The text to search for in the document.

matchCase

boolean

Indicates whether the search should respect case:

  • True : the search is case sensitive.
  • False : the search is case insensitive.

TabsCriteria

A criteria that specifies in which tabs a request executes.

JSON representation
{
  "tabIds": [
    string
  ]
}
Fields
tabIds[]

string

The list of tab IDs in which the request executes.

InsertTextRequest

Inserts text at the specified location.

JSON representation
{
  "text": string,

  // Union field insertion_location can be only one of the following:
  "location": {
    object (Location)
  },
  "endOfSegmentLocation": {
    object (EndOfSegmentLocation)
  }
  // End of list of possible types for union field insertion_location.
}
Fields
text

string

The text to be inserted.

Inserting a newline character will implicitly create a new Paragraph at that index. The paragraph style of the new paragraph will be copied from the paragraph at the current insertion index, including lists and bullets.

Text styles for inserted text will be determined automatically, generally preserving the styling of neighboring text. In most cases, the text style for the inserted text will match the text immediately before the insertion index.

Some control characters (U+0000-U+0008, U+000C-U+001F) and characters from the Unicode Basic Multilingual Plane Private Use Area (U+E000-U+F8FF) will be stripped out of the inserted text.

Union field insertion_location. The location where the text will be inserted. insertion_location can be only one of the following:
location

object (Location)

Inserts the text at a specific index in the document.

Text must be inserted inside the bounds of an existing Paragraph. For instance, text cannot be inserted at a table's start index (i.e. between the table and its preceding paragraph). The text must be inserted in the preceding paragraph.

endOfSegmentLocation

object (EndOfSegmentLocation)

Inserts the text at the end of a header, footer, footnote or the document body.

Location

A particular location in the document.

JSON representation
{
  "segmentId": string,
  "index": integer,
  "tabId": string
}
Fields
segmentId

string

The ID of the header, footer or footnote the location is in. An empty segment ID signifies the document's body.

index

integer

The zero-based index, in UTF-16 code units.

The index is relative to the beginning of the segment specified by segmentId.

tabId

string

The tab that the location is in. When omitted, the request is applied to the first tab.

In a document containing a single tab:

  • If provided, must match the singular tab's ID.

  • If omitted, the request applies to the singular tab.

In a document containing multiple tabs:

  • If provided, the request applies to the specified tab.

  • If omitted, the request applies to the first tab in the document.

EndOfSegmentLocation

Location at the end of a body, header, footer or footnote. The location is immediately before the last newline in the document segment.

JSON representation
{
  "segmentId": string,
  "tabId": string
}
Fields
segmentId

string

The ID of the header, footer or footnote the location is in. An empty segment ID signifies the document's body.

tabId

string

The tab that the location is in. When omitted, the request is applied to the first tab.

In a document containing a single tab:

  • If provided, must match the singular tab's ID.

  • If omitted, the request applies to the singular tab.

In a document containing multiple tabs:

  • If provided, the request applies to the specified tab.

  • If omitted, the request applies to the first tab in the document.

UpdateTextStyleRequest

Update the styling of text.

JSON representation
{
  "textStyle": {
    object (TextStyle)
  },
  "fields": string,

  // Union field insertion_location can be only one of the following:
  "range": {
    object (Range)
  }
  // End of list of possible types for union field insertion_location.
}
Fields
textStyle

object (TextStyle)

The styles to set on the text.

If the value for a particular style matches that of the parent, that style will be set to inherit.

Certain text style changes may cause other changes in order to to mirror the behavior of the Docs editor. See the documentation of TextStyle for more information.

fields

string (FieldMask format)

The fields that should be updated.

At least one field must be specified. The root textStyle is implied and should not be specified. A single "*" can be used as short-hand for listing every field.

For example, to update the text style to bold, set fields to "bold".

To reset a property to its default value, include its field name in the field mask but leave the field itself unset.

Union field insertion_location. The type of range used where the text style will be updated. insertion_location can be only one of the following:
range

object (Range)

The range of text to style.

The range may be extended to include adjacent newlines.

If the range fully contains a paragraph belonging to a list, the paragraph's bullet is also updated with the matching text style.

Ranges cannot be inserted inside a relative UpdateTextStyleRequest.

CreateParagraphBulletsRequest

Creates bullets for all of the paragraphs that overlap with the given range.

The nesting level of each paragraph will be determined by counting leading tabs in front of each paragraph. To avoid excess space between the bullet and the corresponding paragraph, these leading tabs are removed by this request. This may change the indices of parts of the text.

If the paragraph immediately before paragraphs being updated is in a list with a matching preset, the paragraphs being updated are added to that preceding list.

JSON representation
{
  "range": {
    object (Range)
  },
  "bulletPreset": enum (BulletGlyphPreset)
}
Fields
range

object (Range)

The range to apply the bullet preset to.

bulletPreset

enum (BulletGlyphPreset)

The kinds of bullet glyphs to be used.

BulletGlyphPreset

Preset patterns of bullet glyphs for lists.

These patterns use these kinds of bullets:

  • ARROW : An arrow, corresponding to a Unicode U+2794 code point
  • ARROW3D : An arrow with 3D shading, corresponding to a Unicode U+27a2 code point
  • CHECKBOX : A hollow square, corresponding to a Unicode U+274f code point
  • CIRCLE : A hollow circle, corresponding to a Unicode U+25cb code point
  • DIAMOND : A solid diamond, corresponding to a Unicode U+25c6 code point
  • DIAMONDX : A diamond with an 'x', corresponding to a Unicode U+2756 code point
  • HOLLOWDIAMOND : A hollow diamond, corresponding to a Unicode U+25c7 code point
  • DISC : A solid circle, corresponding to a Unicode U+25cf code point
  • SQUARE : A solid square, corresponding to a Unicode U+25a0 code point
  • STAR : A star, corresponding to a Unicode U+2605 code point
  • ALPHA : A lowercase letter, like 'a', 'b', or 'c'.
  • UPPERALPHA : An uppercase letter, like 'A', 'B', or 'C'.
  • DECIMAL : A number, like '1', '2', or '3'.
  • ZERODECIMAL : A number where single digit numbers are prefixed with a zero, like '01', '02', or '03'. Numbers with more than one digit are not prefixed a zero.
  • ROMAN : A lowercase roman numeral, like 'i', 'ii', or 'iii'.
  • UPPERROMAN : A uppercase roman numeral, like 'I', 'II', or 'III'.
  • LEFTTRIANGLE : A triangle pointing left, corresponding to a Unicode U+25c4 code point
Enums
BULLET_GLYPH_PRESET_UNSPECIFIED The bullet glyph preset is unspecified.
BULLET_DISC_CIRCLE_SQUARE A bulleted list with a DISC, CIRCLE and SQUARE bullet glyph for the first 3 list nesting levels.
BULLET_DIAMONDX_ARROW3D_SQUARE A bulleted list with a DIAMONDX, ARROW3D and SQUARE bullet glyph for the first 3 list nesting levels.
BULLET_CHECKBOX A bulleted list with CHECKBOX bullet glyphs for all list nesting levels.
BULLET_ARROW_DIAMOND_DISC A bulleted list with a ARROW, DIAMOND and DISC bullet glyph for the first 3 list nesting levels.
BULLET_STAR_CIRCLE_SQUARE A bulleted list with a STAR, CIRCLE and SQUARE bullet glyph for the first 3 list nesting levels.
BULLET_ARROW3D_CIRCLE_SQUARE A bulleted list with a ARROW3D, CIRCLE and SQUARE bullet glyph for the first 3 list nesting levels.
BULLET_LEFTTRIANGLE_DIAMOND_DISC A bulleted list with a LEFTTRIANGLE, DIAMOND and DISC bullet glyph for the first 3 list nesting levels.
BULLET_DIAMONDX_HOLLOWDIAMOND_SQUARE A bulleted list with a DIAMONDX, HOLLOWDIAMOND and SQUARE bullet glyph for the first 3 list nesting levels.
BULLET_DIAMOND_CIRCLE_SQUARE A bulleted list with a DIAMOND, CIRCLE and SQUARE bullet glyph for the first 3 list nesting levels.
NUMBERED_DECIMAL_ALPHA_ROMAN A numbered list with DECIMAL, ALPHA and ROMAN numeric glyphs for the first 3 list nesting levels, followed by periods.
NUMBERED_DECIMAL_ALPHA_ROMAN_PARENS A numbered list with DECIMAL, ALPHA and ROMAN numeric glyphs for the first 3 list nesting levels, followed by parenthesis.
NUMBERED_DECIMAL_NESTED A numbered list with DECIMAL numeric glyphs separated by periods, where each nesting level uses the previous nesting level's glyph as a prefix. For example: '1.', '1.1.', '2.', '2.2.'.
NUMBERED_UPPERALPHA_ALPHA_ROMAN A numbered list with UPPERALPHA, ALPHA and ROMAN numeric glyphs for the first 3 list nesting levels, followed by periods.
NUMBERED_UPPERROMAN_UPPERALPHA_DECIMAL A numbered list with UPPERROMAN, UPPERALPHA and DECIMAL numeric glyphs for the first 3 list nesting levels, followed by periods.
NUMBERED_ZERODECIMAL_ALPHA_ROMAN A numbered list with ZERODECIMAL, ALPHA and ROMAN numeric glyphs for the first 3 list nesting levels, followed by periods.

DeleteParagraphBulletsRequest

Deletes bullets from all of the paragraphs that overlap with the given range.

The nesting level of each paragraph will be visually preserved by adding indent to the start of the corresponding paragraph.

JSON representation
{
  "range": {
    object (Range)
  }
}
Fields
range

object (Range)

The range to delete bullets from.

CreateNamedRangeRequest

Creates a NamedRange referencing the given range.

JSON representation
{
  "name": string,
  "range": {
    object (Range)
  }
}
Fields
name

string

The name of the NamedRange. Names do not need to be unique.

Names must be at least 1 character and no more than 256 characters, measured in UTF-16 code units.

range

object (Range)

The range to apply the name to.

DeleteNamedRangeRequest

Deletes a NamedRange.

JSON representation
{
  "tabsCriteria": {
    object (TabsCriteria)
  },

  // Union field named_range_reference can be only one of the following:
  "namedRangeId": string,
  "name": string
  // End of list of possible types for union field named_range_reference.
}
Fields
tabsCriteria

object (TabsCriteria)

Optional. The criteria used to specify which tab(s) the range deletion should occur in. When omitted, the range deletion is applied to all tabs.

In a document containing a single tab:

  • If provided, must match the singular tab's ID.

  • If omitted, the range deletion applies to the singular tab.

In a document containing multiple tabs:

  • If provided, the range deletion applies to the specified tabs.

  • If not provided, the range deletion applies to all tabs.

Union field named_range_reference. The value that determines which range or ranges to delete. Exactly one must be set. named_range_reference can be only one of the following:
namedRangeId

string

The ID of the named range to delete.

name

string

The name of the range(s) to delete. All named ranges with the given name will be deleted.

UpdateParagraphStyleRequest

Update the styling of all paragraphs that overlap with the given range.

JSON representation
{
  "paragraphStyle": {
    object (ParagraphStyle)
  },
  "fields": string,

  // Union field insertion_location can be only one of the following:
  "range": {
    object (Range)
  }
  // End of list of possible types for union field insertion_location.
}
Fields
paragraphStyle

object (ParagraphStyle)

The styles to set on the paragraphs.

Certain paragraph style changes may cause other changes in order to mirror the behavior of the Docs editor. See the documentation of ParagraphStyle for more information.

fields

string (FieldMask format)

The fields that should be updated.

At least one field must be specified. The root paragraphStyle is implied and should not be specified. A single "*" can be used as short-hand for listing every field.

For example, to update the paragraph style's alignment property, set fields to "alignment".

To reset a property to its default value, include its field name in the field mask but leave the field itself unset.

Union field insertion_location. The type of range used where the paragraph style will be updated. insertion_location can be only one of the following:
range

object (Range)

The range overlapping the paragraphs to style.

DeleteContentRangeRequest

Deletes content from the document.

JSON representation
{
  "range": {
    object (Range)
  }
}
Fields
range

object (Range)

The range of content to delete.

Deleting text that crosses a paragraph boundary may result in changes to paragraph styles, lists, positioned objects and bookmarks as the two paragraphs are merged.

Attempting to delete certain ranges can result in an invalid document structure in which case a 400 bad request error is returned.

Some examples of invalid delete requests include:

InsertInlineImageRequest

Inserts an InlineObject containing an image at the given location.

JSON representation
{
  "uri": string,
  "objectSize": {
    object (Size)
  },

  // Union field insertion_location can be only one of the following:
  "location": {
    object (Location)
  },
  "endOfSegmentLocation": {
    object (EndOfSegmentLocation)
  }
  // End of list of possible types for union field insertion_location.
}
Fields
uri

string

The image URI.

The image is fetched once at insertion time and a copy is stored for display inside the document. Images must be less than 50MB in size, cannot exceed 25 megapixels, and must be in one of PNG, JPEG, or GIF format.

The provided URI must be publicly accessible and at most 2 kB in length. The URI itself is saved with the image, and exposed via the ImageProperties.content_uri field.

objectSize

object (Size)

The size that the image should appear as in the document. This property is optional and the final size of the image in the document is determined by the following rules: * If neither width nor height is specified, then a default size of the image is calculated based on its resolution. * If one dimension is specified then the other dimension is calculated to preserve the aspect ratio of the image. * If both width and height are specified, the image is scaled to fit within the provided dimensions while maintaining its aspect ratio.

Union field insertion_location. The location where the image will be inserted. insertion_location can be only one of the following:
location

object (Location)

Inserts the image at a specific index in the document.

The image must be inserted inside the bounds of an existing Paragraph. For instance, it cannot be inserted at a table's start index (i.e. between the table and its preceding paragraph).

Inline images cannot be inserted inside a footnote or equation.

endOfSegmentLocation

object (EndOfSegmentLocation)

Inserts the text at the end of a header, footer or the document body.

Inline images cannot be inserted inside a footnote.

InsertTableRequest

Inserts a table at the specified location.

A newline character will be inserted before the inserted table.

JSON representation
{
  "rows": integer,
  "columns": integer,

  // Union field insertion_location can be only one of the following:
  "location": {
    object (Location)
  },
  "endOfSegmentLocation": {
    object (EndOfSegmentLocation)
  }
  // End of list of possible types for union field insertion_location.
}
Fields
rows

integer

The number of rows in the table.

columns

integer

The number of columns in the table.

Union field insertion_location. The location where the table will be inserted. insertion_location can be only one of the following:
location

object (Location)

Inserts the table at a specific model index.

A newline character will be inserted before the inserted table, therefore the table start index will be at the specified location index + 1.

The table must be inserted inside the bounds of an existing Paragraph. For instance, it cannot be inserted at a table's start index (i.e. between an existing table and its preceding paragraph).

Tables cannot be inserted inside a footnote or equation.

endOfSegmentLocation

object (EndOfSegmentLocation)

Inserts the table at the end of the given header, footer or document body. A newline character will be inserted before the inserted table.

Tables cannot be inserted inside a footnote.

InsertTableRowRequest

Inserts an empty row into a table.

JSON representation
{
  "tableCellLocation": {
    object (TableCellLocation)
  },
  "insertBelow": boolean
}
Fields
tableCellLocation

object (TableCellLocation)

The reference table cell location from which rows will be inserted.

A new row will be inserted above (or below) the row where the reference cell is. If the reference cell is a merged cell, a new row will be inserted above (or below) the merged cell.

insertBelow

boolean

Whether to insert new row below the reference cell location.

  • True : insert below the cell.
  • False : insert above the cell.

TableCellLocation

Location of a single cell within a table.

JSON representation
{
  "tableStartLocation": {
    object (Location)
  },
  "rowIndex": integer,
  "columnIndex": integer
}
Fields
tableStartLocation

object (Location)

The location where the table starts in the document.

rowIndex

integer

The zero-based row index. For example, the second row in the table has a row index of 1.

columnIndex

integer

The zero-based column index. For example, the second column in the table has a column index of 1.

InsertTableColumnRequest

Inserts an empty column into a table.

JSON representation
{
  "tableCellLocation": {
    object (TableCellLocation)
  },
  "insertRight": boolean
}
Fields
tableCellLocation

object (TableCellLocation)

The reference table cell location from which columns will be inserted.

A new column will be inserted to the left (or right) of the column where the reference cell is. If the reference cell is a merged cell, a new column will be inserted to the left (or right) of the merged cell.

insertRight

boolean

Whether to insert new column to the right of the reference cell location.

  • True : insert to the right.
  • False : insert to the left.

DeleteTableRowRequest

Deletes a row from a table.

JSON representation
{
  "tableCellLocation": {
    object (TableCellLocation)
  }
}
Fields
tableCellLocation

object (TableCellLocation)

The reference table cell location from which the row will be deleted.

The row this cell spans will be deleted. If this is a merged cell that spans multiple rows, all rows that the cell spans will be deleted. If no rows remain in the table after this deletion, the whole table is deleted.

DeleteTableColumnRequest

Deletes a column from a table.

JSON representation
{
  "tableCellLocation": {
    object (TableCellLocation)
  }
}
Fields
tableCellLocation

object (TableCellLocation)

The reference table cell location from which the column will be deleted.

The column this cell spans will be deleted. If this is a merged cell that spans multiple columns, all columns that the cell spans will be deleted. If no columns remain in the table after this deletion, the whole table is deleted.

InsertPageBreakRequest

Inserts a page break followed by a newline at the specified location.

JSON representation
{

  // Union field insertion_location can be only one of the following:
  "location": {
    object (Location)
  },
  "endOfSegmentLocation": {
    object (EndOfSegmentLocation)
  }
  // End of list of possible types for union field insertion_location.
}
Fields
Union field insertion_location. The location where the page break will be inserted. insertion_location can be only one of the following:
location

object (Location)

Inserts the page break at a specific index in the document.

The page break must be inserted inside the bounds of an existing Paragraph. For instance, it cannot be inserted at a table's start index (i.e. between the table and its preceding paragraph).

Page breaks cannot be inserted inside a table, equation, footnote, header or footer. Since page breaks can only be inserted inside the body, the segment ID field must be empty.

endOfSegmentLocation

object (EndOfSegmentLocation)

Inserts the page break at the end of the document body.

Page breaks cannot be inserted inside a footnote, header or footer. Since page breaks can only be inserted inside the body, the segment ID field must be empty.

DeletePositionedObjectRequest

Deletes a PositionedObject from the document.

JSON representation
{
  "objectId": string,
  "tabId": string
}
Fields
objectId

string

The ID of the positioned object to delete.

tabId

string

The tab that the positioned object to delete is in. When omitted, the request is applied to the first tab.

In a document containing a single tab:

  • If provided, must match the singular tab's ID.

  • If omitted, the request applies to the singular tab.

In a document containing multiple tabs:

  • If provided, the request applies to the specified tab.

  • If omitted, the request applies to the first tab in the document.

UpdateTableColumnPropertiesRequest

Updates the TableColumnProperties of columns in a table.

JSON representation
{
  "tableStartLocation": {
    object (Location)
  },
  "columnIndices": [
    integer
  ],
  "tableColumnProperties": {
    object (TableColumnProperties)
  },
  "fields": string
}
Fields
tableStartLocation

object (Location)

The location where the table starts in the document.

columnIndices[]

integer

The list of zero-based column indices whose property should be updated. If no indices are specified, all columns will be updated.

tableColumnProperties

object (TableColumnProperties)

The table column properties to update.

If the value of tableColumnProperties#width is less than 5 points (5/72 inch), a 400 bad request error is returned.

fields

string (FieldMask format)

The fields that should be updated.

At least one field must be specified. The root tableColumnProperties is implied and should not be specified. A single "*" can be used as short-hand for listing every field.

For example to update the column width, set fields to "width".

UpdateTableCellStyleRequest

Updates the style of a range of table cells.

JSON representation
{
  "tableCellStyle": {
    object (TableCellStyle)
  },
  "fields": string,

  // Union field cells can be only one of the following:
  "tableRange": {
    object (TableRange)
  },
  "tableStartLocation": {
    object (Location)
  }
  // End of list of possible types for union field cells.
}
Fields
tableCellStyle

object (TableCellStyle)

The style to set on the table cells.

When updating borders, if a cell shares a border with an adjacent cell, the corresponding border property of the adjacent cell is updated as well. Borders that are merged and invisible are not updated.

Since updating a border shared by adjacent cells in the same request can cause conflicting border updates, border updates are applied in the following order:

  • borderRight
  • borderLeft
  • borderBottom
  • borderTop
fields

string (FieldMask format)

The fields that should be updated.

At least one field must be specified. The root tableCellStyle is implied and should not be specified. A single "*" can be used as short-hand for listing every field.

For example to update the table cell background color, set fields to "backgroundColor".

To reset a property to its default value, include its field name in the field mask but leave the field itself unset.

Union field cells. The cells which will be updated. cells can be only one of the following:
tableRange

object (TableRange)

The table range representing the subset of the table to which the updates are applied.

tableStartLocation

object (Location)

The location where the table starts in the document. When specified, the updates are applied to all the cells in the table.

TableRange

A table range represents a reference to a subset of a table.

It's important to note that the cells specified by a table range do not necessarily form a rectangle. For example, let's say we have a 3 x 3 table where all the cells of the last row are merged together. The table looks like this:

 [   ][   ][   ]
 [   ][   ][   ]
 [             ]

A table range with table cell location = (tableStartLocation, row = 0, column = 0), row span = 3 and column span = 2 specifies the following cells:

 [ x ][ x ][   ]
 [ x ][ x ][   ]
 [ x    x    x ]
JSON representation
{
  "tableCellLocation": {
    object (TableCellLocation)
  },
  "rowSpan": integer,
  "columnSpan": integer
}
Fields
tableCellLocation

object (TableCellLocation)

The cell location where the table range starts.

rowSpan

integer

The row span of the table range.

columnSpan

integer

The column span of the table range.

UpdateTableRowStyleRequest

Updates the TableRowStyle of rows in a table.

JSON representation
{
  "tableStartLocation": {
    object (Location)
  },
  "rowIndices": [
    integer
  ],
  "tableRowStyle": {
    object (TableRowStyle)
  },
  "fields": string
}
Fields
tableStartLocation

object (Location)

The location where the table starts in the document.

rowIndices[]

integer

The list of zero-based row indices whose style should be updated. If no indices are specified, all rows will be updated.

tableRowStyle

object (TableRowStyle)

The styles to be set on the rows.

fields

string (FieldMask format)

The fields that should be updated.

At least one field must be specified. The root tableRowStyle is implied and should not be specified. A single "*" can be used as short-hand for listing every field.

For example to update the minimum row height, set fields to "minRowHeight".

ReplaceImageRequest

Replaces an existing image with a new image.

Replacing an image removes some image effects from the existing image in order to mirror the behavior of the Docs editor.

JSON representation
{
  "imageObjectId": string,
  "uri": string,
  "imageReplaceMethod": enum (ImageReplaceMethod),
  "tabId": string
}
Fields
imageObjectId

string

The ID of the existing image that will be replaced. The ID can be retrieved from the response of a get request.

uri

string

The URI of the new image.

The image is fetched once at insertion time and a copy is stored for display inside the document. Images must be less than 50MB, cannot exceed 25 megapixels, and must be in PNG, JPEG, or GIF format.

The provided URI can't surpass 2 KB in length. The URI is saved with the image, and exposed through the ImageProperties.source_uri field.

imageReplaceMethod

enum (ImageReplaceMethod)

The replacement method.

tabId

string

The tab that the image to be replaced is in. When omitted, the request is applied to the first tab.

In a document containing a single tab:

  • If provided, must match the singular tab's ID.

  • If omitted, the request applies to the singular tab.

In a document containing multiple tabs:

  • If provided, the request applies to the specified tab.

  • If omitted, the request applies to the first tab in the document.

ImageReplaceMethod

The image replace method.

Enums
IMAGE_REPLACE_METHOD_UNSPECIFIED Unspecified image replace method. This value must not be used.
CENTER_CROP Scales and centers the image to fill the bounds of the original image. The image may be cropped in order to fill the original image's bounds. The rendered size of the image will be the same as the original image.

UpdateDocumentStyleRequest

Updates the DocumentStyle.

JSON representation
{
  "documentStyle": {
    object (DocumentStyle)
  },
  "fields": string,
  "tabId": string
}
Fields
documentStyle

object (DocumentStyle)

The styles to set on the document.

Certain document style changes may cause other changes in order to mirror the behavior of the Docs editor. See the documentation of DocumentStyle for more information.

fields

string (FieldMask format)

The fields that should be updated.

At least one field must be specified. The root documentStyle is implied and should not be specified. A single "*" can be used as short-hand for listing every field.

For example to update the background, set fields to "background".

tabId

string

The tab that contains the style to update. When omitted, the request applies to the first tab.

In a document containing a single tab:

  • If provided, must match the singular tab's ID.

  • If omitted, the request applies to the singular tab.

In a document containing multiple tabs:

  • If provided, the request applies to the specified tab.

  • If not provided, the request applies to the first tab in the document.

MergeTableCellsRequest

Merges cells in a Table.

JSON representation
{
  "tableRange": {
    object (TableRange)
  }
}
Fields
tableRange

object (TableRange)

The table range specifying which cells of the table to merge.

Any text in the cells being merged will be concatenated and stored in the "head" cell of the range. This is the upper-left cell of the range when the content direction is left to right, and the upper-right cell of the range otherwise.

If the range is non-rectangular (which can occur in some cases where the range covers cells that are already merged or where the table is non-rectangular), a 400 bad request error is returned.

UnmergeTableCellsRequest

Unmerges cells in a Table.

JSON representation
{
  "tableRange": {
    object (TableRange)
  }
}
Fields
tableRange

object (TableRange)

The table range specifying which cells of the table to unmerge.

All merged cells in this range will be unmerged, and cells that are already unmerged will not be affected. If the range has no merged cells, the request will do nothing.

If there is text in any of the merged cells, the text will remain in the "head" cell of the resulting block of unmerged cells. The "head" cell is the upper-left cell when the content direction is from left to right, and the upper-right otherwise.

CreateHeaderRequest

Creates a Header. The new header is applied to the SectionStyle at the location of the SectionBreak if specified, otherwise it is applied to the DocumentStyle.

If a header of the specified type already exists, a 400 bad request error is returned.

JSON representation
{
  "type": enum (HeaderFooterType),
  "sectionBreakLocation": {
    object (Location)
  }
}
Fields
type

enum (HeaderFooterType)

The type of header to create.

sectionBreakLocation

object (Location)

The location of the SectionBreak which begins the section this header should belong to. If `sectionBreakLocation' is unset or if it refers to the first section break in the document body, the header applies to the DocumentStyle

HeaderFooterType

The types of headers and footers that can be created.

Enums
DEFAULT A default header/footer.

CreateFooterRequest

Creates a Footer. The new footer is applied to the SectionStyle at the location of the SectionBreak if specified, otherwise it is applied to the DocumentStyle.

If a footer of the specified type already exists, a 400 bad request error is returned.

JSON representation
{
  "type": enum (HeaderFooterType),
  "sectionBreakLocation": {
    object (Location)
  }
}
Fields
type

enum (HeaderFooterType)

The type of footer to create.

sectionBreakLocation

object (Location)

The location of the SectionBreak immediately preceding the section whose SectionStyle this footer should belong to. If this is unset or refers to the first section break in the document, the footer applies to the document style.

CreateFootnoteRequest

Creates a Footnote segment and inserts a new FootnoteReference to it at the given location.

The new Footnote segment will contain a space followed by a newline character.

JSON representation
{

  // Union field footnote_reference_location can be only one of the following:
  "location": {
    object (Location)
  },
  "endOfSegmentLocation": {
    object (EndOfSegmentLocation)
  }
  // End of list of possible types for union field footnote_reference_location.
}
Fields
Union field footnote_reference_location. The location to insert the footnote reference. footnote_reference_location can be only one of the following:
location

object (Location)

Inserts the footnote reference at a specific index in the document.

The footnote reference must be inserted inside the bounds of an existing Paragraph. For instance, it cannot be inserted at a table's start index (i.e. between the table and its preceding paragraph).

Footnote references cannot be inserted inside an equation, header, footer or footnote. Since footnote references can only be inserted in the body, the segment ID field must be empty.

endOfSegmentLocation

object (EndOfSegmentLocation)

Inserts the footnote reference at the end of the document body.

Footnote references cannot be inserted inside a header, footer or footnote. Since footnote references can only be inserted in the body, the segment ID field must be empty.

ReplaceNamedRangeContentRequest

Replaces the contents of the specified NamedRange or NamedRanges with the given replacement content.

Note that an individual NamedRange may consist of multiple discontinuous ranges. In this case, only the content in the first range will be replaced. The other ranges and their content will be deleted.

In cases where replacing or deleting any ranges would result in an invalid document structure, a 400 bad request error is returned.

JSON representation
{
  "tabsCriteria": {
    object (TabsCriteria)
  },

  // Union field replacement_content can be only one of the following:
  "text": string
  // End of list of possible types for union field replacement_content.

  // Union field named_range_reference can be only one of the following:
  "namedRangeId": string,
  "namedRangeName": string
  // End of list of possible types for union field named_range_reference.
}
Fields
tabsCriteria

object (TabsCriteria)

Optional. The criteria used to specify in which tabs the replacement occurs. When omitted, the replacement applies to all tabs.

In a document containing a single tab:

  • If provided, must match the singular tab's ID.

  • If omitted, the replacement applies to the singular tab.

In a document containing multiple tabs:

  • If provided, the replacement applies to the specified tabs.

  • If omitted, the replacement applies to all tabs.

Union field replacement_content. The content to replace the existing content of the named range with. replacement_content can be only one of the following:
text

string

Replaces the content of the specified named range(s) with the given text.

Union field named_range_reference. A reference to the named range(s) whose content will be replaced. named_range_reference can be only one of the following:
namedRangeId

string

The ID of the named range whose content will be replaced.

If there is no named range with the given ID a 400 bad request error is returned.

namedRangeName

string

The name of the NamedRanges whose content will be replaced.

If there are multiple named ranges with the given name, then the content of each one will be replaced. If there are no named ranges with the given name, then the request will be a no-op.

UpdateSectionStyleRequest

Updates the SectionStyle.

JSON representation
{
  "range": {
    object (Range)
  },
  "sectionStyle": {
    object (SectionStyle)
  },
  "fields": string
}
Fields
range

object (Range)

The range overlapping the sections to style.

Because section breaks can only be inserted inside the body, the segment ID field must be empty.

sectionStyle

object (SectionStyle)

The styles to be set on the section.

Certain section style changes may cause other changes in order to mirror the behavior of the Docs editor. See the documentation of SectionStyle for more information.

fields

string (FieldMask format)

The fields that should be updated.

At least one field must be specified. The root sectionStyle is implied and must not be specified. A single "*" can be used as short-hand for listing every field.

For example to update the left margin, set fields to "marginLeft".

InsertSectionBreakRequest

Inserts a section break at the given location.

A newline character will be inserted before the section break.

JSON representation
{
  "sectionType": enum (SectionType),

  // Union field insertion_location can be only one of the following:
  "location": {
    object (Location)
  },
  "endOfSegmentLocation": {
    object (EndOfSegmentLocation)
  }
  // End of list of possible types for union field insertion_location.
}
Fields
sectionType

enum (SectionType)

The type of section to insert.

Union field insertion_location. The location where the break will be inserted. insertion_location can be only one of the following:
location

object (Location)

Inserts a newline and a section break at a specific index in the document.

The section break must be inserted inside the bounds of an existing Paragraph. For instance, it cannot be inserted at a table's start index (i.e. between the table and its preceding paragraph).

Section breaks cannot be inserted inside a table, equation, footnote, header, or footer. Since section breaks can only be inserted inside the body, the segment ID field must be empty.

endOfSegmentLocation

object (EndOfSegmentLocation)

Inserts a newline and a section break at the end of the document body.

Section breaks cannot be inserted inside a footnote, header or footer. Because section breaks can only be inserted inside the body, the segment ID field must be empty.

DeleteHeaderRequest

Deletes a Header from the document.

JSON representation
{
  "headerId": string,
  "tabId": string
}
Fields
headerId

string

The id of the header to delete. If this header is defined on DocumentStyle, the reference to this header is removed, resulting in no header of that type for the first section of the document. If this header is defined on a SectionStyle, the reference to this header is removed and the header of that type is now continued from the previous section.

tabId

string

The tab containing the header to delete. When omitted, the request is applied to the first tab.

In a document containing a single tab:

  • If provided, must match the singular tab's ID.

  • If omitted, the request applies to the singular tab.

In a document containing multiple tabs:

  • If provided, the request applies to the specified tab.

  • If omitted, the request applies to the first tab in the document.

DeleteFooterRequest

Deletes a Footer from the document.

JSON representation
{
  "footerId": string,
  "tabId": string
}
Fields
footerId

string

The id of the footer to delete. If this footer is defined on DocumentStyle, the reference to this footer is removed, resulting in no footer of that type for the first section of the document. If this footer is defined on a SectionStyle, the reference to this footer is removed and the footer of that type is now continued from the previous section.

tabId

string

The tab that contains the footer to delete. When omitted, the request is applied to the first tab.

In a document containing a single tab:

  • If provided, must match the singular tab's ID.

  • If omitted, the request applies to the singular tab.

In a document containing multiple tabs:

  • If provided, the request applies to the specified tab.

  • If omitted, the request applies to the first tab in the document.

PinTableHeaderRowsRequest

Updates the number of pinned table header rows in a table.

JSON representation
{
  "tableStartLocation": {
    object (Location)
  },
  "pinnedHeaderRowsCount": integer
}
Fields
tableStartLocation

object (Location)

The location where the table starts in the document.

pinnedHeaderRowsCount

integer

The number of table rows to pin, where 0 implies that all rows are unpinned.