openapi: 3.1.0
info:
title: Google Docs API
description: Reads and writes Google Docs documents.
version: v1
contact:
name: Google
url: https://google.com
x-twitter: youtube
license:
name: Creative Commons Attribution 3.0
url: http://creativecommons.org/licenses/by/3.0/
termsOfService: https://developers.google.com/terms/
servers:
- url: https://docs.googleapis.com
description: Google Docs API Server
tags:
- name: Documents
description: Operations related to Documents
externalDocs:
url: https://developers.google.com/docs/
paths:
/v1/documents:
post:
tags:
- Documents
summary: Google Post Documents
description: Creates a blank document using the title given in the request. Other fields in the request, including any provided content, are ignored. Returns the created document.
operationId: docs.documents.create
security:
- Oauth2:
- https://www.googleapis.com/auth/documents
Oauth2c:
- https://www.googleapis.com/auth/documents
- Oauth2:
- https://www.googleapis.com/auth/drive
Oauth2c:
- https://www.googleapis.com/auth/drive
- Oauth2:
- https://www.googleapis.com/auth/drive.file
Oauth2c:
- https://www.googleapis.com/auth/drive.file
parameters:
- description: V1 error format.
in: query
name: $.xgafv
schema:
enum:
- '1'
- '2'
type: string
- description: OAuth access token.
in: query
name: access_token
schema:
type: string
- description: Data format for response.
in: query
name: alt
schema:
enum:
- json
- media
- proto
type: string
- description: JSONP
in: query
name: callback
schema:
type: string
- description: Selector specifying which fields to include in a partial response.
in: query
name: fields
schema:
type: string
- description: API key. Your API key identifies your project and provides you with API access, quota, and reports. Required unless you provide an OAuth 2.0 token.
in: query
name: key
schema:
type: string
- description: OAuth 2.0 token for the current user.
in: query
name: oauth_token
schema:
type: string
- description: Returns response with indentations and line breaks.
in: query
name: prettyPrint
schema:
type: boolean
- description: Available to use for quota purposes for server-side applications. Can be any arbitrary string assigned to a user, but should not exceed 40 characters.
in: query
name: quotaUser
schema:
type: string
- description: Upload protocol for media (e.g. "raw", "multipart").
in: query
name: upload_protocol
schema:
type: string
- description: Legacy upload protocol for media (e.g. "media", "multipart").
in: query
name: uploadType
schema:
type: string
- in: header
name: Authorization
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Document'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Document'
x-api-evangelist-certified: '2025-07-20'
x-api-naftiko-published: '2025-07-20'
x-microcks-operation:
delay: 100
dispatcher: FALLBACK
dispatcherRules: SuccessExample
/v1/documents/{documentId}:
get:
tags:
- Documents
summary: Google Get Documents
description: Gets the latest version of the specified document.
operationId: docs.documents.get
security:
- Oauth2:
- https://www.googleapis.com/auth/documents
Oauth2c:
- https://www.googleapis.com/auth/documents
- Oauth2:
- https://www.googleapis.com/auth/documents.readonly
Oauth2c:
- https://www.googleapis.com/auth/documents.readonly
- Oauth2:
- https://www.googleapis.com/auth/drive
Oauth2c:
- https://www.googleapis.com/auth/drive
- Oauth2:
- https://www.googleapis.com/auth/drive.file
Oauth2c:
- https://www.googleapis.com/auth/drive.file
- Oauth2:
- https://www.googleapis.com/auth/drive.readonly
Oauth2c:
- https://www.googleapis.com/auth/drive.readonly
parameters:
- description: The ID of the document to retrieve.
in: path
name: documentId
required: true
schema:
type: string
- description: The suggestions view mode to apply to the document. This allows viewing the document with all suggestions inline, accepted or rejected. If one is not specified, DEFAULT_FOR_CURRENT_ACCESS is used.
in: query
name: suggestionsViewMode
schema:
enum:
- DEFAULT_FOR_CURRENT_ACCESS
- SUGGESTIONS_INLINE
- PREVIEW_SUGGESTIONS_ACCEPTED
- PREVIEW_WITHOUT_SUGGESTIONS
type: string
- description: V1 error format.
in: query
name: $.xgafv
schema:
enum:
- '1'
- '2'
type: string
- description: OAuth access token.
in: query
name: access_token
schema:
type: string
- description: Data format for response.
in: query
name: alt
schema:
enum:
- json
- media
- proto
type: string
- description: JSONP
in: query
name: callback
schema:
type: string
- description: Selector specifying which fields to include in a partial response.
in: query
name: fields
schema:
type: string
- description: API key. Your API key identifies your project and provides you with API access, quota, and reports. Required unless you provide an OAuth 2.0 token.
in: query
name: key
schema:
type: string
- description: OAuth 2.0 token for the current user.
in: query
name: oauth_token
schema:
type: string
- description: Returns response with indentations and line breaks.
in: query
name: prettyPrint
schema:
type: boolean
- description: Available to use for quota purposes for server-side applications. Can be any arbitrary string assigned to a user, but should not exceed 40 characters.
in: query
name: quotaUser
schema:
type: string
- description: Upload protocol for media (e.g. "raw", "multipart").
in: query
name: upload_protocol
schema:
type: string
- description: Legacy upload protocol for media (e.g. "media", "multipart").
in: query
name: uploadType
schema:
type: string
- in: header
name: Authorization
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Document'
x-api-evangelist-certified: '2025-07-20'
x-api-naftiko-published: '2025-07-20'
x-microcks-operation:
delay: 100
dispatcher: FALLBACK
dispatcherRules: SuccessExample
/v1/documents/{documentId}:batchUpdate:
post:
tags:
- Documents
summary: Google Post Documents Batch Update
description: 'Applies one or more updates to the document. Each request is validated before being applied. If any request is not valid, then the entire request will fail and nothing will be applied. Some requests have replies to give you some information about how they are applied. Other requests do not need to return information; these each return an empty reply. The order of replies matches that of the requests. For example, suppose you call batchUpdate with four updates, and only the third one returns information. The response would have two empty replies, the reply to the third request, and another empty reply, in that order. Because other users may be editing the document, the document might not exactly reflect your changes: your changes may be altered with respect to collaborator changes. If there are no collaborators, the document should reflect your changes. In any case, the updates in your request are guaranteed to be applied together atomically.'
operationId: docs.documents.batchUpdate
security:
- Oauth2:
- https://www.googleapis.com/auth/documents
Oauth2c:
- https://www.googleapis.com/auth/documents
- Oauth2:
- https://www.googleapis.com/auth/drive
Oauth2c:
- https://www.googleapis.com/auth/drive
- Oauth2:
- https://www.googleapis.com/auth/drive.file
Oauth2c:
- https://www.googleapis.com/auth/drive.file
parameters:
- description: The ID of the document to update.
in: path
name: documentId
required: true
schema:
type: string
- description: V1 error format.
in: query
name: $.xgafv
schema:
enum:
- '1'
- '2'
type: string
- description: OAuth access token.
in: query
name: access_token
schema:
type: string
- description: Data format for response.
in: query
name: alt
schema:
enum:
- json
- media
- proto
type: string
- description: JSONP
in: query
name: callback
schema:
type: string
- description: Selector specifying which fields to include in a partial response.
in: query
name: fields
schema:
type: string
- description: API key. Your API key identifies your project and provides you with API access, quota, and reports. Required unless you provide an OAuth 2.0 token.
in: query
name: key
schema:
type: string
- description: OAuth 2.0 token for the current user.
in: query
name: oauth_token
schema:
type: string
- description: Returns response with indentations and line breaks.
in: query
name: prettyPrint
schema:
type: boolean
- description: Available to use for quota purposes for server-side applications. Can be any arbitrary string assigned to a user, but should not exceed 40 characters.
in: query
name: quotaUser
schema:
type: string
- description: Upload protocol for media (e.g. "raw", "multipart").
in: query
name: upload_protocol
schema:
type: string
- description: Legacy upload protocol for media (e.g. "media", "multipart").
in: query
name: uploadType
schema:
type: string
- in: header
name: Authorization
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BatchUpdateDocumentRequest'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/BatchUpdateDocumentResponse'
x-microcks-operation:
delay: 100
dispatcher: FALLBACK
dispatcherRules: SuccessExample
components:
schemas:
AutoText:
description: A ParagraphElement representing a spot in the text that's dynamically replaced with content that can change over time, like a page number.
properties:
suggestedDeletionIds:
description: The suggested deletion IDs. If empty, then there are no suggested deletions of this content.
items:
type: string
type: array
suggestedInsertionIds:
description: The suggested insertion IDs. An AutoText may have multiple insertion IDs if it's a nested suggested change. If empty, then this is not a suggested insertion.
items:
type: string
type: array
suggestedTextStyleChanges:
additionalProperties:
$ref: '#/components/schemas/SuggestedTextStyle'
description: The suggested text style changes to this AutoText, keyed by suggestion ID.
type: object
textStyle:
$ref: '#/components/schemas/TextStyle'
description: The text style of this AutoText.
type:
description: The type of this auto text.
enum:
- TYPE_UNSPECIFIED
- PAGE_NUMBER
- PAGE_COUNT
type: string
type: object
Background:
description: Represents the background of a document.
properties:
color:
$ref: '#/components/schemas/OptionalColor'
description: The background color.
type: object
BackgroundSuggestionState:
description: A mask that indicates which of the fields on the base Background have been changed in this suggestion. For any field set to true, the Backgound has a new suggested value.
properties:
backgroundColorSuggested:
description: Indicates whether the current background color has been modified in this suggestion.
type: boolean
type: object
BatchUpdateDocumentRequest:
description: Request message for BatchUpdateDocument.
properties:
requests:
description: A list of updates to apply to the document.
items:
$ref: '#/components/schemas/Request'
type: array
writeControl:
$ref: '#/components/schemas/WriteControl'
description: Provides control over how write requests are executed.
type: object
BatchUpdateDocumentResponse:
description: Response message from a BatchUpdateDocument request.
properties:
documentId:
description: The ID of the document to which the updates were applied to.
type: string
replies:
description: The reply of the updates. This maps 1:1 with the updates, although replies to some requests may be empty.
items:
$ref: '#/components/schemas/Response'
type: array
writeControl:
$ref: '#/components/schemas/WriteControl'
description: The updated write control after applying the request.
type: object
Body:
description: The document body. The body typically contains the full document contents except for headers, footers, and footnotes.
properties:
content:
description: The contents of the body. The indexes for the body's content begin at zero.
items:
$ref: '#/components/schemas/StructuralElement'
type: array
type: object
Bullet:
description: Describes the bullet of a paragraph.
properties:
listId:
description: The ID of the list this paragraph belongs to.
type: string
nestingLevel:
description: The nesting level of this paragraph in the list.
format: int32
type: integer
textStyle:
$ref: '#/components/schemas/TextStyle'
description: The paragraph-specific text style applied to this bullet.
type: object
BulletSuggestionState:
description: A mask that indicates which of the fields on the base Bullet have been changed in this suggestion. For any field set to true, there's a new suggested value.
properties:
listIdSuggested:
description: Indicates if there was a suggested change to the list_id.
type: boolean
nestingLevelSuggested:
description: Indicates if there was a suggested change to the nesting_level.
type: boolean
textStyleSuggestionState:
$ref: '#/components/schemas/TextStyleSuggestionState'
description: A mask that indicates which of the fields in text style have been changed in this suggestion.
type: object
Color:
description: A solid color.
properties:
rgbColor:
$ref: '#/components/schemas/RgbColor'
description: The RGB color value.
type: object
ColumnBreak:
description: A ParagraphElement representing a column break. A column break makes the subsequent text start at the top of the next column.
properties:
suggestedDeletionIds:
description: The suggested deletion IDs. If empty, then there are no suggested deletions of this content.
items:
type: string
type: array
suggestedInsertionIds:
description: The suggested insertion IDs. A ColumnBreak may have multiple insertion IDs if it's a nested suggested change. If empty, then this is not a suggested insertion.
items:
type: string
type: array
suggestedTextStyleChanges:
additionalProperties:
$ref: '#/components/schemas/SuggestedTextStyle'
description: The suggested text style changes to this ColumnBreak, keyed by suggestion ID.
type: object
textStyle:
$ref: '#/components/schemas/TextStyle'
description: The text style of this ColumnBreak. Similar to text content, like text runs and footnote references, the text style of a column break can affect content layout as well as the styling of text inserted next to it.
type: object
CreateFooterRequest:
description: 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.
properties:
sectionBreakLocation:
$ref: '#/components/schemas/Location'
description: 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.
type:
description: The type of footer to create.
enum:
- HEADER_FOOTER_TYPE_UNSPECIFIED
- DEFAULT
type: string
type: object
CreateFooterResponse:
description: The result of creating a footer.
properties:
footerId:
description: The ID of the created footer.
type: string
type: object
CreateFootnoteRequest:
description: 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.
properties:
endOfSegmentLocation:
$ref: '#/components/schemas/EndOfSegmentLocation'
description: 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.
location:
$ref: '#/components/schemas/Location'
description: 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.
type: object
CreateFootnoteResponse:
description: The result of creating a footnote.
properties:
footnoteId:
description: The ID of the created footnote.
type: string
type: object
CreateHeaderRequest:
description: 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.
properties:
sectionBreakLocation:
$ref: '#/components/schemas/Location'
description: The location of the SectionBreak which begins the section this header should belong to. If `section_break_location' is unset or if it refers to the first section break in the document body, the header applies to the DocumentStyle
type:
description: The type of header to create.
enum:
- HEADER_FOOTER_TYPE_UNSPECIFIED
- DEFAULT
type: string
type: object
CreateHeaderResponse:
description: The result of creating a header.
properties:
headerId:
description: The ID of the created header.
type: string
type: object
CreateNamedRangeRequest:
description: Creates a NamedRange referencing the given range.
properties:
name:
description: 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.
type: string
range:
$ref: '#/components/schemas/Range'
description: The range to apply the name to.
type: object
CreateNamedRangeResponse:
description: The result of creating a named range.
properties:
namedRangeId:
description: The ID of the created named range.
type: string
type: object
CreateParagraphBulletsRequest:
description: 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.
properties:
bulletPreset:
description: The kinds of bullet glyphs to be used.
enum:
- BULLET_GLYPH_PRESET_UNSPECIFIED
- BULLET_DISC_CIRCLE_SQUARE
- BULLET_DIAMONDX_ARROW3D_SQUARE
- BULLET_CHECKBOX
- BULLET_ARROW_DIAMOND_DISC
- BULLET_STAR_CIRCLE_SQUARE
- BULLET_ARROW3D_CIRCLE_SQUARE
- BULLET_LEFTTRIANGLE_DIAMOND_DISC
- BULLET_DIAMONDX_HOLLOWDIAMOND_SQUARE
- BULLET_DIAMOND_CIRCLE_SQUARE
- NUMBERED_DECIMAL_ALPHA_ROMAN
- NUMBERED_DECIMAL_ALPHA_ROMAN_PARENS
- NUMBERED_DECIMAL_NESTED
- NUMBERED_UPPERALPHA_ALPHA_ROMAN
- NUMBERED_UPPERROMAN_UPPERALPHA_DECIMAL
- NUMBERED_ZERODECIMAL_ALPHA_ROMAN
type: string
range:
$ref: '#/components/schemas/Range'
description: The range to apply the bullet preset to.
type: object
CropProperties:
description: The crop properties of an image. The crop rectangle is represented using fractional offsets from the original content's 4 edges. - If the offset is in the interval (0, 1), the corresponding edge of crop rectangle is positioned inside of the image's original bounding rectangle. - If the offset is negative or greater than 1, the corresponding edge of crop rectangle is positioned outside of the image's original bounding rectangle. - If all offsets and rotation angle are 0, the image is not cropped.
properties:
angle:
description: The clockwise rotation angle of the crop rectangle around its center, in radians. Rotation is applied after the offsets.
format: float
type: number
offsetBottom:
description: The offset specifies how far inwards the bottom edge of the crop rectangle is from the bottom edge of the original content as a fraction of the original content's height.
format: float
type: number
offsetLeft:
description: The offset specifies how far inwards the left edge of the crop rectangle is from the left edge of the original content as a fraction of the original content's width.
format: float
type: number
offsetRight:
description: The offset specifies how far inwards the right edge of the crop rectangle is from the right edge of the original content as a fraction of the original content's width.
format: float
type: number
offsetTop:
description: The offset specifies how far inwards the top edge of the crop rectangle is from the top edge of the original content as a fraction of the original content's height.
format: float
type: number
type: object
CropPropertiesSuggestionState:
description: A mask that indicates which of the fields on the base CropProperties have been changed in this suggestion. For any field set to true, there's a new suggested value.
properties:
angleSuggested:
description: Indicates if there was a suggested change to angle.
type: boolean
offsetBottomSuggested:
description: Indicates if there was a suggested change to offset_bottom.
type: boolean
offsetLeftSuggested:
description: Indicates if there was a suggested change to offset_left.
type: boolean
offsetRightSuggested:
description: Indicates if there was a suggested change to offset_right.
type: boolean
offsetTopSuggested:
description: Indicates if there was a suggested change to offset_top.
type: boolean
type: object
DeleteContentRangeRequest:
description: Deletes content from the document.
properties:
range:
$ref: '#/components/schemas/Range'
description: '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: * Deleting one code unit of a surrogate pair. * Deleting the last newline character of a Body, Header, Footer, Footnote, TableCell or TableOfContents. * Deleting the start or end of a Table, TableOfContents or Equation without deleting the entire element. * Deleting the newline character before a Table, TableOfContents or SectionBreak without deleting the element. * Deleting individual rows or cells of a table. Deleting the content within a table cell is allowed.'
type: object
DeleteFooterRequest:
description: Deletes a Footer from the document.
properties:
footerId:
description: 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.
type: string
type: object
DeleteHeaderRequest:
description: Deletes a Header from the document.
properties:
headerId:
description: 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.
type: string
type: object
DeleteNamedRangeRequest:
description: Deletes a NamedRange.
properties:
name:
description: The name of the range(s) to delete. All named ranges with the given name will be deleted.
type: string
namedRangeId:
description: The ID of the named range to delete.
type: string
type: object
DeleteParagraphBulletsRequest:
description: 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.
properties:
range:
$ref: '#/components/schemas/Range'
description: The range to delete bullets from.
type: object
DeletePositionedObjectRequest:
description: Deletes a PositionedObject from the document.
properties:
objectId:
description: The ID of the positioned object to delete.
type: string
type: object
DeleteTableColumnRequest:
description: Deletes a column from a table.
properties:
tableCellLocation:
$ref: '#/components/schemas/TableCellLocation'
description: 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.
type: object
DeleteTableRowRequest:
description: Deletes a row from a table.
properties:
tableCellLocation:
$ref: '#/components/schemas/TableCellLocation'
description: 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.
type: object
Dimension:
description: A magnitude in a single direction in the specified units.
properties:
magnitude:
description: The magnitude.
format: double
type: number
unit:
description: The units for magnitude.
enum:
- UNIT_UNSPECIFIED
- PT
type: string
type: object
Document:
description: A Google Docs document.
properties:
body:
$ref: '#/components/schemas/Body'
description: Output only. The main body of the document.
documentId:
description: Output only. The ID of the document.
type: string
documentStyle:
$ref: '#/components/schemas/DocumentStyle'
description: Output only. The style of the document.
footers:
additionalProperties:
$ref: '#/components/schemas/Footer'
description: Output only. The footers in the document, keyed by footer ID.
type: object
footnotes:
additionalProperties:
$ref: '#/components/schemas/Footnote'
description: Output only. The footnotes in the document, keyed by footnote ID.
type: object
headers:
additionalProperties:
$ref: '#/components/schemas/Header'
description: Output only. The headers in the document, keyed by header ID.
type: object
# --- truncated at 32 KB (171 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/google/refs/heads/main/openapi/google-docs-api-openapi.yml