Google Docs Documents API

openapi: 3.2.0
info:
  title: Google Docs Documents API
  description: The Google Docs API lets you create, read, and edit Google Docs documents. You can use it to programmatically create and modify documents, apply formatting, insert content, and manage document structure including paragraphs, tables, headers, footers, and inline objects.
  version: v1
  termsOfService: https://developers.google.com/terms
  contact:
    name: Google
    url: https://developers.google.com/docs/api/support
  license:
    name: Creative Commons Attribution 4.0
    url: https://creativecommons.org/licenses/by/4.0/
  x-logo:
    url: https://www.gstatic.com/images/branding/product/2x/docs_48dp.png
servers:
- url: https://docs.googleapis.com
  description: Google Docs API production server
security:
- oauth2: []
tags:
- name: Documents
  description: Operations on Google Docs documents
paths:
  /v1/documents:
    post:
      operationId: docs.documents.create
      summary: Google Docs Create a Document
      description: Creates a blank document using the title given in the request. Other fields in the request, including any provided content, are ignored.
      tags:
      - Documents
      requestBody:
        description: The document to create. Only the title field is used.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDocumentRequest'
            examples:
              DocsDocumentsCreateRequestExample:
                summary: Default docs.documents.create request
                x-microcks-default: true
                value:
                  title: Example Title
      responses:
        '200':
          description: Successful response containing the newly created document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
              examples:
                DocsDocumentsCreate200Example:
                  summary: Default docs.documents.create 200 response
                  x-microcks-default: true
                  value:
                    documentId: '500123'
                    title: Example Title
                    tabs:
                    - childTabs: {}
                    revisionId: '500123'
                    suggestionsViewMode: DEFAULT_FOR_CURRENT_ACCESS
                    body:
                      content:
                      - {}
                    headers: example_value
                    footers: example_value
                    footnotes: example_value
                    documentStyle:
                      defaultHeaderId: '500123'
                      defaultFooterId: '500123'
                      evenPageHeaderId: '500123'
                      evenPageFooterId: '500123'
                      firstPageHeaderId: '500123'
                      firstPageFooterId: '500123'
                      useFirstPageHeaderFooter: true
                      useEvenPageHeaderFooter: true
                      pageNumberStart: 10
                      useCustomHeaderFooterMargins: true
                      flipPageOrientation: true
                    suggestedDocumentStyleChanges: example_value
                    namedStyles:
                      styles:
                      - {}
                    suggestedNamedStylesChanges: example_value
                    lists: example_value
                    namedRanges: example_value
                    inlineObjects: example_value
                    positionedObjects: example_value
        '400':
          description: Bad request. The request was invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                DocsDocumentsCreate400Example:
                  summary: Default docs.documents.create 400 response
                  x-microcks-default: true
                  value:
                    error:
                      code: 10
                      message: example_value
                      status: example_value
                      details:
                      - {}
        '401':
          description: Unauthorized. Authentication credentials are missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                DocsDocumentsCreate401Example:
                  summary: Default docs.documents.create 401 response
                  x-microcks-default: true
                  value:
                    error:
                      code: 10
                      message: example_value
                      status: example_value
                      details:
                      - {}
        '403':
          description: Forbidden. The caller does not have permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                DocsDocumentsCreate403Example:
                  summary: Default docs.documents.create 403 response
                  x-microcks-default: true
                  value:
                    error:
                      code: 10
                      message: example_value
                      status: example_value
                      details:
                      - {}
      security:
      - oauth2:
        - https://www.googleapis.com/auth/documents
      - oauth2:
        - https://www.googleapis.com/auth/drive
      - oauth2:
        - https://www.googleapis.com/auth/drive.file
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/documents/{documentId}:
    get:
      operationId: docs.documents.get
      summary: Google Docs Get a Document
      description: Gets the latest version of the specified document. Returns the full document resource including content, styling, and metadata.
      tags:
      - Documents
      parameters:
      - name: documentId
        in: path
        required: true
        description: The ID of the document to retrieve.
        schema:
          type: string
        example: '500123'
      - name: suggestionsViewMode
        in: query
        required: false
        description: The suggestions view mode to apply to the document. This allows viewing the document with all suggestions inline, collapsed, or only previewing suggestions accepted or rejected. If not specified, defaults to DEFAULT_FOR_CURRENT_ACCESS.
        schema:
          $ref: '#/components/schemas/SuggestionsViewMode'
        example: example_value
      - name: includeTabsContent
        in: query
        required: false
        description: Whether to populate the Document.tabs field instead of the text content fields like body, documentStyle, headers, etc. When true, content is returned in Document.tabs. When false, content from the first tab populates the legacy content fields.
        schema:
          type: boolean
        example: true
      responses:
        '200':
          description: Successful response containing the requested document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
              examples:
                DocsDocumentsGet200Example:
                  summary: Default docs.documents.get 200 response
                  x-microcks-default: true
                  value:
                    documentId: '500123'
                    title: Example Title
                    tabs:
                    - childTabs: {}
                    revisionId: '500123'
                    suggestionsViewMode: DEFAULT_FOR_CURRENT_ACCESS
                    body:
                      content:
                      - {}
                    headers: example_value
                    footers: example_value
                    footnotes: example_value
                    documentStyle:
                      defaultHeaderId: '500123'
                      defaultFooterId: '500123'
                      evenPageHeaderId: '500123'
                      evenPageFooterId: '500123'
                      firstPageHeaderId: '500123'
                      firstPageFooterId: '500123'
                      useFirstPageHeaderFooter: true
                      useEvenPageHeaderFooter: true
                      pageNumberStart: 10
                      useCustomHeaderFooterMargins: true
                      flipPageOrientation: true
                    suggestedDocumentStyleChanges: example_value
                    namedStyles:
                      styles:
                      - {}
                    suggestedNamedStylesChanges: example_value
                    lists: example_value
                    namedRanges: example_value
                    inlineObjects: example_value
                    positionedObjects: example_value
        '401':
          description: Unauthorized. Authentication credentials are missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                DocsDocumentsGet401Example:
                  summary: Default docs.documents.get 401 response
                  x-microcks-default: true
                  value:
                    error:
                      code: 10
                      message: example_value
                      status: example_value
                      details:
                      - {}
        '403':
          description: Forbidden. The caller does not have permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                DocsDocumentsGet403Example:
                  summary: Default docs.documents.get 403 response
                  x-microcks-default: true
                  value:
                    error:
                      code: 10
                      message: example_value
                      status: example_value
                      details:
                      - {}
        '404':
          description: Not found. The specified document does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                DocsDocumentsGet404Example:
                  summary: Default docs.documents.get 404 response
                  x-microcks-default: true
                  value:
                    error:
                      code: 10
                      message: example_value
                      status: example_value
                      details:
                      - {}
      security:
      - oauth2:
        - https://www.googleapis.com/auth/documents
      - oauth2:
        - https://www.googleapis.com/auth/documents.readonly
      - oauth2:
        - https://www.googleapis.com/auth/drive
      - oauth2:
        - https://www.googleapis.com/auth/drive.readonly
      - oauth2:
        - https://www.googleapis.com/auth/drive.file
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/documents/{documentId}:batchUpdate:
    post:
      operationId: docs.documents.batchUpdate
      summary: Google Docs Batch Update a Document
      description: Applies one or more updates to the document. Each request is validated before being applied. If any request is not valid, 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 the order of requests.
      tags:
      - Documents
      parameters:
      - name: documentId
        in: path
        required: true
        description: The ID of the document to update.
        schema:
          type: string
        example: '500123'
      requestBody:
        description: The batch update request containing one or more document updates.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchUpdateDocumentRequest'
            examples:
              DocsDocumentsBatchupdateRequestExample:
                summary: Default docs.documents.batchUpdate request
                x-microcks-default: true
                value:
                  requests:
                  - {}
                  writeControl:
                    requiredRevisionId: '500123'
                    targetRevisionId: '500123'
      responses:
        '200':
          description: Successful response containing the document ID, ordered replies for each request, and updated write control information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchUpdateDocumentResponse'
              examples:
                DocsDocumentsBatchupdate200Example:
                  summary: Default docs.documents.batchUpdate 200 response
                  x-microcks-default: true
                  value:
                    documentId: '500123'
                    replies:
                    - {}
                    writeControl:
                      requiredRevisionId: '500123'
                      targetRevisionId: '500123'
        '400':
          description: Bad request. One or more of the update requests were invalid. Nothing was applied to the document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                DocsDocumentsBatchupdate400Example:
                  summary: Default docs.documents.batchUpdate 400 response
                  x-microcks-default: true
                  value:
                    error:
                      code: 10
                      message: example_value
                      status: example_value
                      details:
                      - {}
        '401':
          description: Unauthorized. Authentication credentials are missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                DocsDocumentsBatchupdate401Example:
                  summary: Default docs.documents.batchUpdate 401 response
                  x-microcks-default: true
                  value:
                    error:
                      code: 10
                      message: example_value
                      status: example_value
                      details:
                      - {}
        '403':
          description: Forbidden. The caller does not have permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                DocsDocumentsBatchupdate403Example:
                  summary: Default docs.documents.batchUpdate 403 response
                  x-microcks-default: true
                  value:
                    error:
                      code: 10
                      message: example_value
                      status: example_value
                      details:
                      - {}
        '404':
          description: Not found. The specified document does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                DocsDocumentsBatchupdate404Example:
                  summary: Default docs.documents.batchUpdate 404 response
                  x-microcks-default: true
                  value:
                    error:
                      code: 10
                      message: example_value
                      status: example_value
                      details:
                      - {}
      security:
      - oauth2:
        - https://www.googleapis.com/auth/documents
      - oauth2:
        - https://www.googleapis.com/auth/drive
      - oauth2:
        - https://www.googleapis.com/auth/drive.file
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Color:
      type: object
      description: A solid color.
      properties:
        rgbColor:
          $ref: '#/components/schemas/RgbColor'
    ParagraphBorder:
      type: object
      description: A border around a paragraph.
      properties:
        color:
          $ref: '#/components/schemas/OptionalColor'
        width:
          $ref: '#/components/schemas/Dimension'
        padding:
          $ref: '#/components/schemas/Dimension'
        dashStyle:
          type: string
          enum:
          - DASH_STYLE_UNSPECIFIED
          - SOLID
          - DOT
          - DASH
          example: DASH_STYLE_UNSPECIFIED
    InlineObjectProperties:
      type: object
      description: Properties of an InlineObject.
      properties:
        embeddedObject:
          $ref: '#/components/schemas/EmbeddedObject'
    SheetsChartReference:
      type: object
      description: A reference to a linked chart embedded from Google Sheets.
      properties:
        spreadsheetId:
          type: string
          description: The ID of the Google Sheets spreadsheet that contains the source chart.
          example: '500123'
        chartId:
          type: integer
          description: The ID of the specific chart in the Sheets spreadsheet.
          example: '500123'
    PersonProperties:
      type: object
      description: Properties specific to a linked person.
      properties:
        name:
          type: string
          description: Output only. The name of the person.
          readOnly: true
          example: Example Title
        email:
          type: string
          description: Output only. The email address linked to this person.
          readOnly: true
          example: user@example.com
    DocumentStyle:
      type: object
      description: The style of the document, influencing the look of the document and any defaults for new content.
      properties:
        background:
          $ref: '#/components/schemas/Background'
        defaultHeaderId:
          type: string
          description: The ID of the default header.
          example: '500123'
        defaultFooterId:
          type: string
          description: The ID of the default footer.
          example: '500123'
        evenPageHeaderId:
          type: string
          description: The ID of the header used for even pages.
          example: '500123'
        evenPageFooterId:
          type: string
          description: The ID of the footer used for even pages.
          example: '500123'
        firstPageHeaderId:
          type: string
          description: The ID of the header used for the first page.
          example: '500123'
        firstPageFooterId:
          type: string
          description: The ID of the footer used for the first page.
          example: '500123'
        useFirstPageHeaderFooter:
          type: boolean
          description: Whether to use the first page header/footer IDs for the first page of the document.
          example: true
        useEvenPageHeaderFooter:
          type: boolean
          description: Whether to use the even page header/footer IDs for even pages.
          example: true
        pageNumberStart:
          type: integer
          description: The page number from which to start counting the number of pages.
          example: 10
        marginTop:
          $ref: '#/components/schemas/Dimension'
        marginBottom:
          $ref: '#/components/schemas/Dimension'
        marginRight:
          $ref: '#/components/schemas/Dimension'
        marginLeft:
          $ref: '#/components/schemas/Dimension'
        pageSize:
          $ref: '#/components/schemas/Size'
        marginHeader:
          $ref: '#/components/schemas/Dimension'
        marginFooter:
          $ref: '#/components/schemas/Dimension'
        useCustomHeaderFooterMargins:
          type: boolean
          description: Whether to use custom header/footer margins.
          example: true
        flipPageOrientation:
          type: boolean
          description: Whether to flip the orientation of the page to landscape, which effectively swaps the width and height of the page size.
          example: true
    Location:
      type: object
      description: A particular location in the document.
      properties:
        segmentId:
          type: string
          description: The ID of the header, footer, or footnote the location is in. An empty segment ID signifies the document body.
          example: '500123'
        index:
          type: integer
          description: The zero-based index, in UTF-16 code units. The index is relative to the beginning of the segment specified by segmentId.
          example: 10
        tabId:
          type: string
          description: The tab that the location is in.
          example: '500123'
    ReplaceAllTextRequest:
      type: object
      description: Replaces all instances of text matching a criteria with replace text.
      properties:
        containsText:
          $ref: '#/components/schemas/SubstringMatchCriteria'
        replaceText:
          type: string
          description: The text that will replace the matched text.
          example: example_value
        tabsCriteria:
          $ref: '#/components/schemas/TabsCriteria'
      required:
      - containsText
      - replaceText
    Request:
      type: object
      description: A single update to apply to a document. Exactly one field must be set.
      properties:
        insertText:
          $ref: '#/components/schemas/InsertTextRequest'
        deleteContentRange:
          $ref: '#/components/schemas/DeleteContentRangeRequest'
        insertInlineImage:
          $ref: '#/components/schemas/InsertInlineImageRequest'
        insertTable:
          $ref: '#/components/schemas/InsertTableRequest'
        insertTableRow:
          $ref: '#/components/schemas/InsertTableRowRequest'
        insertTableColumn:
          $ref: '#/components/schemas/InsertTableColumnRequest'
        deleteTableRow:
          $ref: '#/components/schemas/DeleteTableRowRequest'
        deleteTableColumn:
          $ref: '#/components/schemas/DeleteTableColumnRequest'
        insertPageBreak:
          $ref: '#/components/schemas/InsertPageBreakRequest'
        insertSectionBreak:
          $ref: '#/components/schemas/InsertSectionBreakRequest'
        deletePositionedObject:
          $ref: '#/components/schemas/DeletePositionedObjectRequest'
        updateTextStyle:
          $ref: '#/components/schemas/UpdateTextStyleRequest'
        updateParagraphStyle:
          $ref: '#/components/schemas/UpdateParagraphStyleRequest'
        updateTableCellStyle:
          $ref: '#/components/schemas/UpdateTableCellStyleRequest'
        updateTableRowStyle:
          $ref: '#/components/schemas/UpdateTableRowStyleRequest'
        updateTableColumnProperties:
          $ref: '#/components/schemas/UpdateTableColumnPropertiesRequest'
        updateDocumentStyle:
          $ref: '#/components/schemas/UpdateDocumentStyleRequest'
        updateSectionStyle:
          $ref: '#/components/schemas/UpdateSectionStyleRequest'
        replaceAllText:
          $ref: '#/components/schemas/ReplaceAllTextRequest'
        createNamedRange:
          $ref: '#/components/schemas/CreateNamedRangeRequest'
        deleteNamedRange:
          $ref: '#/components/schemas/DeleteNamedRangeRequest'
        replaceNamedRangeContent:
          $ref: '#/components/schemas/ReplaceNamedRangeContentRequest'
        createParagraphBullets:
          $ref: '#/components/schemas/CreateParagraphBulletsRequest'
        deleteParagraphBullets:
          $ref: '#/components/schemas/DeleteParagraphBulletsRequest'
        createHeader:
          $ref: '#/components/schemas/CreateHeaderRequest'
        createFooter:
          $ref: '#/components/schemas/CreateFooterRequest'
        createFootnote:
          $ref: '#/components/schemas/CreateFootnoteRequest'
        deleteHeader:
          $ref: '#/components/schemas/DeleteHeaderRequest'
        deleteFooter:
          $ref: '#/components/schemas/DeleteFooterRequest'
        replaceImage:
          $ref: '#/components/schemas/ReplaceImageRequest'
        mergeTableCells:
          $ref: '#/components/schemas/MergeTableCellsRequest'
        unmergeTableCells:
          $ref: '#/components/schemas/UnmergeTableCellsRequest'
        pinTableHeaderRows:
          $ref: '#/components/schemas/PinTableHeaderRowsRequest'
    WriteControl:
      type: object
      description: Provides control over how write requests are executed. When set on a request, it provides a way to detect conflicts.
      properties:
        requiredRevisionId:
          type: string
          description: The optional revision ID of the document the write request is applied to. If this is not the latest revision of the document, the request is not processed and returns a 400 bad request error.
          example: '500123'
        targetRevisionId:
          type: string
          description: The optional target revision ID of the document the write request is applied to. If collaborator changes have occurred after the document was read using the API, the changes produced by this write request are applied against the collaborator changes. This results in a resolved document.
          example: '500123'
    Bullet:
      type: object
      description: Describes the bullet of a paragraph.
      properties:
        listId:
          type: string
          description: The ID of the list this paragraph belongs to.
          example: '500123'
        nestingLevel:
          type: integer
          description: The nesting level of this paragraph in the list.
          example: 10
        textStyle:
          $ref: '#/components/schemas/TextStyle'
    TableColumnProperties:
      type: object
      description: The properties of a column in a table.
      properties:
        widthType:
          type: string
          description: The width type of the column.
          enum:
          - WIDTH_TYPE_UNSPECIFIED
          - EVENLY_DISTRIBUTED
          - FIXED_WIDTH
          example: WIDTH_TYPE_UNSPECIFIED
        width:
          $ref: '#/components/schemas/Dimension'
    NamedRange:
      type: object
      description: A collection of Ranges that have the same named range ID.
      properties:
        namedRangeId:
          type: string
          description: The ID of the named range.
          example: '500123'
        name:
          type: string
          description: The name of the named range.
          example: Example Title
        ranges:
          type: array
          description: The ranges that belong to this named range.
          items:
            $ref: '#/components/schemas/Range'
          example: []
    NestingLevel:
      type: object
      description: Contains properties describing the look and feel of a list bullet at a given level of nesting.
      properties:
        bulletAlignment:
          type: string
          description: The alignment of the bullet within the space allotted for rendering.
          enum:
          - BULLET_ALIGNMENT_UNSPECIFIED
          - START
          - CENTER
          - END
          example: BULLET_ALIGNMENT_UNSPECIFIED
        glyphFormat:
          type: string
          description: The format string used by bullets at this level of nesting.
          example: example_value
        indentFirstLine:
          $ref: '#/components/schemas/Dimension'
        indentStart:
          $ref: '#/components/schemas/Dimension'
        textStyle:
          $ref: '#/components/schemas/TextStyle'
        startNumber:
          type: integer
          description: The number of the first list item at this nesting level.
          example: 10
        glyphType:
          type: string
          description: The type of glyph used by bullets at this nesting level.
          enum:
          - GLYPH_TYPE_UNSPECIFIED
          - NONE
          - DECIMAL
          - ZERO_DECIMAL
          - UPPER_ALPHA
          - ALPHA
          - UPPER_ROMAN
          - ROMAN
          example: GLYPH_TYPE_UNSPECIFIED
        glyphSymbol:
          type: string
          description: A custom glyph symbol used by bullets at this nesting level.
          example: example_value
    CreateFooterRequest:
      type: object
      description: Creates a Footer.
      properties:
        type:
          type: string
          description: The type of footer to create.
          enum:
          - HEADER_FOOTER_TYPE_UNSPECIFIED
          - DEFAULT
          example: HEADER_FOOTER_TYPE_UNSPECIFIED
        sectionBreakLocation:
          $ref: '#/components/schemas/Location'
      required:
      - type
    RichLink:
      type: object
      description: A link to a Google resource such as a file in Drive, a YouTube video, or a Calendar event.
      properties:
        richLinkId:
          type: string
          description: Output only. The ID of this link.
          readOnly: true
          example: '500123'
        richLinkProperties:
          $ref: '#/components/schemas/RichLinkProperties'
        suggestedInsertionIds:
          type: array
          items:
            type: string
          example: []
        suggestedDeletionIds:
          type: array
          items:
            type: string
          example: []
        suggestedTextStyleChanges:
          type: object
          additionalProperties:
            type: object
          example: example_value
        textStyle:
          $ref: '#/components/schemas/TextStyle'
    Person:
      type: object
      description: A person or email address mentioned in a document.
      properties:
        personId:
          type: string
          description: Output only. The unique ID of this link.
          readOnly: true
          example: '500123'
        personProperties:
          $ref: '#/components/schemas/PersonProperties'
        suggestedInsertionIds:
          type: array
          items:
            type: string
          example: []
        suggestedDeletionIds:
          type: array
          items:
            type: string
          example: []
        suggestedTextStyleChanges:
          type: object
          additionalProperties:
            type: object
          example: example_value
        textStyle:
          $ref: '#/components/schemas/TextStyle'
    TextRun:
      type: object
      description: A ParagraphElement that represents a run of text that all has the same styling.
      properties:
        content:
          type: string
          description: The text of this run. Any non-text elements in the run are replaced with the Unicode character U+E907.
          example: example_value
        textStyle:
          $ref: '#/components/schemas/TextStyle'
        suggestedInsertionIds:
          type: array
          description: The suggested insertion IDs.
          items:
            type: string
          example: []
        suggestedDeletionIds:
          type: array
          description: The suggested deletion IDs.
          items:
            type: string
          example: []
        suggestedTextStyleChanges:
          type: object
          description: Suggested changes to the text style, keyed by suggestion ID.
          additionalProperties:
            type: object
          example: example_value
    Error:
      type: object
      description: Error response from the Google Docs API.
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
              description: The HTTP status code.
            message:
              type: string
              description: A human-readable description of the error.
            status:
              type: string
              description: The status code string.
            details:
              type: array
              description: Additional error details.
              items:
                type: object
          example: example_value
    DeleteFooterRequest:
      type: object
      description: Deletes a Footer from the document.
      properties:
        footerId:
          type: string
          description: The ID of the footer to delete.
          example: '500123'
        tabId:
          type: string
          description: The tab containing the footer to dele

# --- truncated at 32 KB (96 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/google-docs/refs/heads/main/openapi/google-docs-documents-api-openapi.yml