Google Docs API

openapi: 3.1.0
info:
  title: Google Docs 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
externalDocs:
  description: Google Docs API documentation
  url: https://developers.google.com/docs/api/reference/rest
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:
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authentication for Google APIs.
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.google.com/o/oauth2/auth
          tokenUrl: https://oauth2.googleapis.com/token
          scopes:
            https://www.googleapis.com/auth/documents: >-
              View and manage your Google Docs documents
            https://www.googleapis.com/auth/documents.readonly: >-
              View your Google Docs documents
            https://www.googleapis.com/auth/drive: >-
              See, edit, create, and delete all of your Google Drive files
            https://www.googleapis.com/auth/drive.readonly: >-
              See and download all your Google Drive files
            https://www.googleapis.com/auth/drive.file: >-
              View and manage Google Drive files and folders that you have
              opened or created with this app
  schemas:
    CreateDocumentRequest:
      type: object
      description: Request body for creating a new document. Only the title is used.
      properties:
        title:
          type: string
          description: The title of the document to create.
          example: Example Title
      required:
      - title

    Document:
      type: object
      description: >-
        A Google Docs document. The Document resource represents the full
        content and metadata of a document.
      properties:
        documentId:
          type: string
          description: Output only. The ID of the document.
          readOnly: true
          example: '500123'
        title:
          type: string
          description: The title of the document.
          example: Example Title
        tabs:
          type: array
          description: >-
            Tabs that are part of a document. Tabs can contain child tabs,
            creating a nested tab structure.
          items:
            $ref: '#/components/schemas/Tab'
          example: []
        revisionId:
          type: string
          description: >-
            Output only. The revision ID of the document. Can be used in
            update requests to specify which revision of a document to
            apply updates to, and how the request should behave if the
            document has been edited since that revision.
          readOnly: true
          example: '500123'
        suggestionsViewMode:
          $ref: '#/components/schemas/SuggestionsViewMode'
        body:
          $ref: '#/components/schemas/Body'
        headers:
          type: object
          description: >-
            Output only. The headers in the document, keyed by header ID.
          additionalProperties:
            $ref: '#/components/schemas/Header'
          readOnly: true
          example: example_value
        footers:
          type: object
          description: >-
            Output only. The footers in the document, keyed by footer ID.
          additionalProperties:
            $ref: '#/components/schemas/Footer'
          readOnly: true
          example: example_value
        footnotes:
          type: object
          description: >-
            Output only. The footnotes in the document, keyed by footnote ID.
          additionalProperties:
            $ref: '#/components/schemas/Footnote'
          readOnly: true
          example: example_value
        documentStyle:
          $ref: '#/components/schemas/DocumentStyle'
        suggestedDocumentStyleChanges:
          type: object
          description: >-
            Output only. The suggested changes to the style of the document,
            keyed by suggestion ID.
          additionalProperties:
            type: object
          readOnly: true
          example: example_value
        namedStyles:
          $ref: '#/components/schemas/NamedStyles'
        suggestedNamedStylesChanges:
          type: object
          description: >-
            Output only. The suggested changes to the named styles of the
            document, keyed by suggestion ID.
          additionalProperties:
            type: object
          readOnly: true
          example: example_value
        lists:
          type: object
          description: >-
            Output only. The lists in the document, keyed by list ID.
          additionalProperties:
            $ref: '#/components/schemas/List'
          readOnly: true
          example: example_value
        namedRanges:
          type: object
          description: >-
            Output only. The named ranges in the document, keyed by name.
          additionalProperties:
            $ref: '#/components/schemas/NamedRanges'
          readOnly: true
          example: example_value
        inlineObjects:
          type: object
          description: >-
            Output only. The inline objects in the document, keyed by
            object ID.
          additionalProperties:
            $ref: '#/components/schemas/InlineObject'
          readOnly: true
          example: example_value
        positionedObjects:
          type: object
          description: >-
            Output only. The positioned objects in the document, keyed by
            object ID.
          additionalProperties:
            $ref: '#/components/schemas/PositionedObject'
          readOnly: true

          example: example_value
    Tab:
      type: object
      description: >-
        A tab within a document. Tabs can contain content and can be nested
        with child tabs.
      properties:
        tabProperties:
          $ref: '#/components/schemas/TabProperties'
        childTabs:
          type: array
          description: The child tabs nested within this tab.
          items:
            $ref: '#/components/schemas/Tab'
          example: []
        documentTab:
          $ref: '#/components/schemas/DocumentTab'

    TabProperties:
      type: object
      description: Properties of a tab.
      properties:
        tabId:
          type: string
          description: Output only. The ID of the tab.
          readOnly: true
          example: '500123'
        title:
          type: string
          description: The title of the tab.
          example: Example Title
        parentTabId:
          type: string
          description: >-
            Output only. The ID of the parent tab. Empty if this is a
            root-level tab.
          readOnly: true
          example: '500123'
        index:
          type: integer
          description: The zero-based index of the tab amongst its siblings.

          example: 10
    DocumentTab:
      type: object
      description: >-
        The content of a tab in a document, containing the body and
        associated document-level properties.
      properties:
        body:
          $ref: '#/components/schemas/Body'
        headers:
          type: object
          description: The headers in this tab, keyed by header ID.
          additionalProperties:
            $ref: '#/components/schemas/Header'
          example: example_value
        footers:
          type: object
          description: The footers in this tab, keyed by footer ID.
          additionalProperties:
            $ref: '#/components/schemas/Footer'
          example: example_value
        footnotes:
          type: object
          description: The footnotes in this tab, keyed by footnote ID.
          additionalProperties:
            $ref: '#/components/schemas/Footnote'
          example: example_value
        documentStyle:
          $ref: '#/components/schemas/DocumentStyle'
        namedStyles:
          $ref: '#/components/schemas/NamedStyles'
        lists:
          type: object
          description: The lists in this tab, keyed by list ID.
          additionalProperties:
            $ref: '#/components/schemas/List'
          example: example_value
        namedRanges:
          type: object
          description: The named ranges in this tab, keyed by name.
          additionalProperties:
            $ref: '#/components/schemas/NamedRanges'
          example: example_value
        inlineObjects:
          type: object
          description: The inline objects in this tab, keyed by object ID.
          additionalProperties:
            $ref: '#/components/schemas/InlineObject'
          example: example_value
        positionedObjects:
          type: object
          description: The positioned objects in this tab, keyed by object ID.
          additionalProperties:
            $ref: '#/components/schemas/PositionedObject'

          example: example_value
    Body:
      type: object
      description: >-
        The document body. The body typically contains the full content of
        the document.
      properties:
        content:
          type: array
          description: >-
            The contents of the body. Elements in the body are ordered by
            their start index.
          items:
            $ref: '#/components/schemas/StructuralElement'

          example: []
    StructuralElement:
      type: object
      description: >-
        A StructuralElement describes content that provides structure to
        the document.
      properties:
        startIndex:
          type: integer
          description: The zero-based start index of this structural element.
          example: 10
        endIndex:
          type: integer
          description: The zero-based end index of this structural element, exclusive.
          example: 10
        paragraph:
          $ref: '#/components/schemas/Paragraph'
        sectionBreak:
          $ref: '#/components/schemas/SectionBreak'
        table:
          $ref: '#/components/schemas/Table'
        tableOfContents:
          $ref: '#/components/schemas/TableOfContents'

    Paragraph:
      type: object
      description: >-
        A StructuralElement representing a paragraph. A paragraph is a
        range of content that is terminated with a newline character.
      properties:
        elements:
          type: array
          description: The content of the paragraph, broken into its component parts.
          items:
            $ref: '#/components/schemas/ParagraphElement'
          example: []
        paragraphStyle:
          $ref: '#/components/schemas/ParagraphStyle'
        bullet:
          $ref: '#/components/schemas/Bullet'
        suggestedParagraphStyleChanges:
          type: object
          description: Suggested changes to the paragraph style, keyed by suggestion ID.
          additionalProperties:
            type: object
          example: example_value
        suggestedBulletChanges:
          type: object
          description: Suggested changes to the bullet, keyed by suggestion ID.
          additionalProperties:
            type: object
          example: example_value
        positionedObjectIds:
          type: array
          description: >-
            The IDs of the positioned objects tethered to this paragraph.
          items:
            type: string

          example: []
    ParagraphElement:
      type: object
      description: >-
        A ParagraphElement describes content within a paragraph.
      properties:
        startIndex:
          type: integer
          description: The zero-based start index of this paragraph element.
          example: 10
        endIndex:
          type: integer
          description: The zero-based end index of this paragraph element, exclusive.
          example: 10
        textRun:
          $ref: '#/components/schemas/TextRun'
        autoText:
          $ref: '#/components/schemas/AutoText'
        pageBreak:
          $ref: '#/components/schemas/PageBreak'
        columnBreak:
          $ref: '#/components/schemas/ColumnBreak'
        footnoteReference:
          $ref: '#/components/schemas/FootnoteReference'
        horizontalRule:
          $ref: '#/components/schemas/HorizontalRule'
        equation:
          $ref: '#/components/schemas/Equation'
        inlineObjectElement:
          $ref: '#/components/schemas/InlineObjectElement'
        person:
          $ref: '#/components/schemas/Person'
        richLink:
          $ref: '#/components/schemas/RichLink'

    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
    TextStyle:
      type: object
      description: >-
        Represents the styling that can be applied to text. Inherited text
        styles are represented as unset fields. A text style's parent
        depends on where the text style is defined.
      properties:
        bold:
          type: boolean
          description: Whether the text is bold.
          example: true
        italic:
          type: boolean
          description: Whether the text is italicized.
          example: true
        underline:
          type: boolean
          description: Whether the text is underlined.
          example: true
        strikethrough:
          type: boolean
          description: Whether the text is struck through.
          example: true
        smallCaps:
          type: boolean
          description: Whether the text is in small capital letters.
          example: true
        backgroundColor:
          $ref: '#/components/schemas/OptionalColor'
        foregroundColor:
          $ref: '#/components/schemas/OptionalColor'
        fontSize:
          $ref: '#/components/schemas/Dimension'
        weightedFontFamily:
          $ref: '#/components/schemas/WeightedFontFamily'
        baselineOffset:
          type: string
          description: >-
            The text's vertical offset from its normal position.
          enum:
          - BASELINE_OFFSET_UNSPECIFIED
          - NONE
          - SUPERSCRIPT
          - SUBSCRIPT
          example: BASELINE_OFFSET_UNSPECIFIED
        link:
          $ref: '#/components/schemas/Link'

    ParagraphStyle:
      type: object
      description: >-
        Styles that apply to a whole paragraph. Inherited paragraph styles
        are represented as unset fields.
      properties:
        headingId:
          type: string
          description: The heading ID of the paragraph.
          example: '500123'
        namedStyleType:
          type: string
          description: The named style type of the paragraph.
          enum:
          - NAMED_STYLE_TYPE_UNSPECIFIED
          - NORMAL_TEXT
          - TITLE
          - SUBTITLE
          - HEADING_1
          - HEADING_2
          - HEADING_3
          - HEADING_4
          - HEADING_5
          - HEADING_6
          example: NAMED_STYLE_TYPE_UNSPECIFIED
        alignment:
          type: string
          description: The text alignment for this paragraph.
          enum:
          - ALIGNMENT_UNSPECIFIED
          - START
          - CENTER
          - END
          - JUSTIFIED
          example: ALIGNMENT_UNSPECIFIED
        lineSpacing:
          type: number
          description: >-
            The amount of space between lines as a percentage of normal,
            where normal is represented as 100.0.
          example: 42.5
  

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