openapi: 3.0.3
info:
  title: Microsoft Word JavaScript API
  description: >-
    RESTful representation of the Office JavaScript API for Word add-ins. This
    API provides strongly-typed objects for document manipulation, content
    controls, tables, formatting, comments, collaboration, and shapes within
    Word documents through the Office Add-ins platform.
  version: 1.0.0
  contact:
    name: Microsoft Office Add-ins Support
    url: https://learn.microsoft.com/en-us/office/dev/add-ins/
  license:
    name: Microsoft API License
    url: https://www.microsoft.com/en-us/legal/terms-of-use
  x-generated-from: documentation
  x-last-validated: '2026-04-18'
  x-api-type: JavaScript
servers:
  - url: https://word.officeapps.live.com/api/v1
    description: Word JavaScript API conceptual endpoint
security:
  - oauth2: []
tags:
  - name: Documents
    description: Operations for creating, opening, and managing Word documents
  - name: Body
    description: Operations on the document body content
  - name: Paragraphs
    description: Operations for managing paragraphs in documents
  - name: Content Controls
    description: Operations for managing content controls
  - name: Tables
    description: Operations for creating and managing tables
  - name: Comments
    description: Operations for managing comments and replies
  - name: Sections
    description: Operations for managing document sections
  - name: Styles
    description: Operations for managing document styles
  - name: Properties
    description: Operations for managing document properties
paths:
  /documents:
    post:
      operationId: createDocument
      summary: Microsoft Word Create Document
      description: Create a new blank Word document.
      tags:
        - Documents
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDocumentRequest'
      responses:
        '201':
          description: Successfully created a new document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /documents/{document-id}:
    get:
      operationId: getDocument
      summary: Microsoft Word Get Document
      description: Get the properties and metadata of a Word document.
      tags:
        - Documents
      parameters:
        - $ref: '#/components/parameters/documentId'
      responses:
        '200':
          description: Successfully retrieved document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /documents/{document-id}/body:
    get:
      operationId: getBody
      summary: Microsoft Word Get Body
      description: Get the body object of the document containing the main content.
      tags:
        - Body
      parameters:
        - $ref: '#/components/parameters/documentId'
      responses:
        '200':
          description: Successfully retrieved document body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Body'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /documents/{document-id}/body/insertText:
    post:
      operationId: insertText
      summary: Microsoft Word Insert Text
      description: Insert text at the specified location in the document body.
      tags:
        - Body
      parameters:
        - $ref: '#/components/parameters/documentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InsertTextRequest'
      responses:
        '200':
          description: Successfully inserted text.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Range'
        '400':
          $ref: '#/components/responses/BadRequest'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /documents/{document-id}/body/insertHtml:
    post:
      operationId: insertHtml
      summary: Microsoft Word Insert HTML
      description: Insert HTML content at the specified location in the document body.
      tags:
        - Body
      parameters:
        - $ref: '#/components/parameters/documentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InsertHtmlRequest'
      responses:
        '200':
          description: Successfully inserted HTML.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Range'
        '400':
          $ref: '#/components/responses/BadRequest'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /documents/{document-id}/paragraphs:
    get:
      operationId: listParagraphs
      summary: Microsoft Word List Paragraphs
      description: Get the collection of paragraph objects in the document body.
      tags:
        - Paragraphs
      parameters:
        - $ref: '#/components/parameters/documentId'
      responses:
        '200':
          description: Successfully retrieved paragraphs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParagraphCollection'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /documents/{document-id}/paragraphs/{paragraph-id}:
    get:
      operationId: getParagraph
      summary: Microsoft Word Get Paragraph
      description: Get a specific paragraph by its ID.
      tags:
        - Paragraphs
      parameters:
        - $ref: '#/components/parameters/documentId'
        - $ref: '#/components/parameters/paragraphId'
      responses:
        '200':
          description: Successfully retrieved paragraph.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Paragraph'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteParagraph
      summary: Microsoft Word Delete Paragraph
      description: Delete a paragraph from the document.
      tags:
        - Paragraphs
      parameters:
        - $ref: '#/components/parameters/documentId'
        - $ref: '#/components/parameters/paragraphId'
      responses:
        '204':
          description: Successfully deleted the paragraph.
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /documents/{document-id}/contentControls:
    get:
      operationId: listContentControls
      summary: Microsoft Word List Content Controls
      description: Get the collection of content control objects in the document.
      tags:
        - Content Controls
      parameters:
        - $ref: '#/components/parameters/documentId'
      responses:
        '200':
          description: Successfully retrieved content controls.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentControlCollection'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /documents/{document-id}/contentControls/{control-id}:
    get:
      operationId: getContentControl
      summary: Microsoft Word Get Content Control
      description: Get a specific content control by its ID.
      tags:
        - Content Controls
      parameters:
        - $ref: '#/components/parameters/documentId'
        - name: control-id
          in: path
          required: true
          description: The unique identifier of the content control.
          schema:
            type: string
          example: '500123'
      responses:
        '200':
          description: Successfully retrieved content control.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentControl'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /documents/{document-id}/tables:
    get:
      operationId: listTables
      summary: Microsoft Word List Tables
      description: Get the collection of table objects in the document body.
      tags:
        - Tables
      parameters:
        - $ref: '#/components/parameters/documentId'
      responses:
        '200':
          description: Successfully retrieved tables.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TableCollection'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: insertTable
      summary: Microsoft Word Insert Table
      description: Insert a table with the specified number of rows and columns.
      tags:
        - Tables
      parameters:
        - $ref: '#/components/parameters/documentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InsertTableRequest'
      responses:
        '201':
          description: Successfully created the table.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Table'
        '400':
          $ref: '#/components/responses/BadRequest'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /documents/{document-id}/comments:
    get:
      operationId: listComments
      summary: Microsoft Word List Comments
      description: Get the collection of comments in the document.
      tags:
        - Comments
      parameters:
        - $ref: '#/components/parameters/documentId'
      responses:
        '200':
          description: Successfully retrieved comments.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentCollection'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /documents/{document-id}/sections:
    get:
      operationId: listSections
      summary: Microsoft Word List Sections
      description: Get the collection of section objects in the document.
      tags:
        - Sections
      parameters:
        - $ref: '#/components/parameters/documentId'
      responses:
        '200':
          description: Successfully retrieved sections.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SectionCollection'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /documents/{document-id}/properties:
    get:
      operationId: getDocumentProperties
      summary: Microsoft Word Get Document Properties
      description: Get the document properties including title, subject, author, and custom properties.
      tags:
        - Properties
      parameters:
        - $ref: '#/components/parameters/documentId'
      responses:
        '200':
          description: Successfully retrieved document properties.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentProperties'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: updateDocumentProperties
      summary: Microsoft Word Update Document Properties
      description: Update the document properties such as title, subject, and author.
      tags:
        - Properties
      parameters:
        - $ref: '#/components/parameters/documentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentPropertiesUpdate'
      responses:
        '200':
          description: Successfully updated document properties.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentProperties'
        '400':
          $ref: '#/components/responses/BadRequest'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /documents/{document-id}/body/search:
    post:
      operationId: searchDocument
      summary: Microsoft Word Search Document
      description: Search the document body for text matching the specified criteria.
      tags:
        - Body
      parameters:
        - $ref: '#/components/parameters/documentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
      responses:
        '200':
          description: Successfully completed search.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RangeCollection'
        '400':
          $ref: '#/components/responses/BadRequest'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /documents/{document-id}/styles:
    get:
      operationId: listStyles
      summary: Microsoft Word List Styles
      description: Get the collection of style objects in the document.
      tags:
        - Styles
      parameters:
        - $ref: '#/components/parameters/documentId'
      responses:
        '200':
          description: Successfully retrieved styles.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StyleCollection'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /documents/{document-id}/save:
    post:
      operationId: saveDocument
      summary: Microsoft Word Save Document
      description: Save the document. This persists the file using the Word file format.
      tags:
        - Documents
      parameters:
        - $ref: '#/components/parameters/documentId'
      responses:
        '204':
          description: Successfully saved the document.
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 via Microsoft Identity Platform for Office Add-ins.
      flows:
        authorizationCode:
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
          tokenUrl: https://login.microsoftonline.com/common/oauth2/v2.0/token
          scopes:
            Files.ReadWrite: Read and write files
  parameters:
    documentId:
      name: document-id
      in: path
      required: true
      description: The unique identifier of the Word document.
      schema:
        type: string
      example: doc-a1b2c3d4
    paragraphId:
      name: paragraph-id
      in: path
      required: true
      description: The unique identifier of the paragraph.
      schema:
        type: string
      example: para-500123
  responses:
    Unauthorized:
      description: Authentication required.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Invalid request parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    Document:
      type: object
      description: Represents a Word document.
      properties:
        id:
          type: string
          description: Unique identifier for the document.
          example: doc-a1b2c3d4
        saved:
          type: boolean
          description: Whether the document has been saved.
          example: true
        changeTrackingMode:
          type: string
          description: Change tracking mode (Off, TrackAll, TrackMineOnly).
          example: 'Off'
    CreateDocumentRequest:
      type: object
      description: Request to create a new document.
      properties:
        base64File:
          type: string
          description: Base64-encoded document content for the new document.
    Body:
      type: object
      description: Represents the body of a document or section.
      properties:
        text:
          type: string
          description: Plain text content of the body.
          example: This is the document body text.
        type:
          type: string
          description: Type of the body (MainDoc, Section, Header, Footer, TableCell).
          example: MainDoc
        style:
          type: string
          description: Style name applied to the body.
          example: Normal
    InsertTextRequest:
      type: object
      description: Request to insert text into the document.
      required:
        - text
        - location
      properties:
        text:
          type: string
          description: The text to insert.
          example: Hello, World!
        location:
          type: string
          description: Location to insert text (Start, End, Before, After, Replace).
          example: End
    InsertHtmlRequest:
      type: object
      description: Request to insert HTML content into the document.
      required:
        - html
        - location
      properties:
        html:
          type: string
          description: The HTML content to insert.
          example: <h1>Title</h1><p>Body paragraph</p>
        location:
          type: string
          description: Location to insert HTML (Start, End, Before, After, Replace).
          example: End
    Paragraph:
      type: object
      description: Represents a single paragraph in a document.
      properties:
        id:
          type: string
          description: Unique identifier of the paragraph.
          example: para-500123
        text:
          type: string
          description: Plain text content of the paragraph.
          example: This is a sample paragraph.
        style:
          type: string
          description: Style name applied to the paragraph.
          example: Heading 1
        alignment:
          type: string
          description: Text alignment (Left, Centered, Right, Justified).
          example: Left
        firstLineIndent:
          type: number
          description: First line indent value in points.
          example: 36.0
        lineSpacing:
          type: number
          description: Line spacing in points.
          example: 15.0
        outlineLevel:
          type: integer
          description: Outline level of the paragraph (1-9).
          example: 1
        isListItem:
          type: boolean
          description: Whether the paragraph is part of a list.
          example: false
    ParagraphCollection:
      type: object
      description: Collection of paragraphs.
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/Paragraph'
    ContentControl:
      type: object
      description: Represents a content control in a document.
      properties:
        id:
          type: string
          description: Unique identifier of the content control.
          example: '500123'
        tag:
          type: string
          description: Tag to identify the content control.
          example: customer_name
        title:
          type: string
          description: Title of the content control.
          example: Customer Name
        type:
          type: string
          description: Type of content control (RichText, PlainText, Picture, CheckBox, DropDownList, ComboBox, DatePicker).
          example: RichText
        text:
          type: string
          description: Text content of the content control.
          example: Contoso Ltd.
        appearance:
          type: string
          description: Visual appearance (BoundingBox, Tags, Hidden).
          example: BoundingBox
        cannotDelete:
          type: boolean
          description: Whether the content control can be deleted.
          example: false
        cannotEdit:
          type: boolean
          description: Whether the content control can be edited.
          example: false
    ContentControlCollection:
      type: object
      description: Collection of content controls.
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/ContentControl'
    Table:
      type: object
      description: Represents a table in a Word document.
      properties:
        id:
          type: string
          description: Unique identifier of the table.
          example: tbl-500123
        rowCount:
          type: integer
          description: Number of rows in the table.
          example: 5
        columnCount:
          type: integer
          description: Number of columns in the table.
          example: 3
        style:
          type: string
          description: Style name applied to the table.
          example: Grid Table 1 Light
        alignment:
          type: string
          description: Table alignment (Left, Centered, Right).
          example: Centered
        headerRowCount:
          type: integer
          description: Number of header rows.
          example: 1
    TableCollection:
      type: object
      description: Collection of tables.
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/Table'
    InsertTableRequest:
      type: object
      description: Request to insert a table.
      required:
        - rowCount
        - columnCount
      properties:
        rowCount:
          type: integer
          description: Number of rows for the new table.
          example: 3
        columnCount:
          type: integer
          description: Number of columns for the new table.
          example: 4
        insertLocation:
          type: string
          description: Where to insert the table (Start, End, Before, After).
          example: End
        values:
          type: array
          description: 2D array of cell values.
          items:
            type: array
            items:
              type: string
          example:
            - - Name
              - Age
              - City
              - Country
    Comment:
      type: object
      description: Represents a comment in a Word document.
      properties:
        id:
          type: string
          description: Unique identifier of the comment.
          example: comment-500123
        authorName:
          type: string
          description: Name of the comment author.
          example: Jane Smith
        authorEmail:
          type: string
          description: Email of the comment author.
          example: jsmith@contoso.com
        content:
          type: string
          description: Text content of the comment.
          example: Please review this section.
        createdDate:
          type: string
          format: date-time
          description: When the comment was created.
          example: '2025-03-15T14:30:00Z'
        resolved:
          type: boolean
          description: Whether the comment has been resolved.
          example: false
    CommentCollection:
      type: object
      description: Collection of comments.
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/Comment'
    Section:
      type: object
      description: Represents a section in a Word document.
      properties:
        id:
          type: string
          description: Unique identifier of the section.
          example: section-01
    SectionCollection:
      type: object
      description: Collection of sections.
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/Section'
    DocumentProperties:
      type: object
      description: Document properties and metadata.
      properties:
        title:
          type: string
          description: Title of the document.
          example: Quarterly Report Q4 2025
        subject:
          type: string
          description: Subject of the document.
          example: Financial Reports
        author:
          type: string
          description: Author of the document.
          example: Jane Smith
        manager:
          type: string
          description: Manager listed in the properties.
          example: John Doe
        company:
          type: string
          description: Company listed in the properties.
          example: Contoso Ltd.
        category:
          type: string
          description: Category of the document.
          example: Reports
        keywords:
          type: string
          description: Keywords associated with the document.
          example: financial, quarterly, 2025
        comments:
          type: string
          description: Comments metadata field.
          example: Draft version
        creationDate:
          type: string
          format: date-time
          description: When the document was created.
          example: '2025-01-15T10:00:00Z'
        lastSaveTime:
          type: string
          format: date-time
          description: When the document was last saved.
          example: '2025-03-15T14:30:00Z'
        revisionNumber:
          type: string
          description: Revision number of the document.
          example: '12'
    DocumentPropertiesUpdate:
      type: object
      description: Properties to update on a document.
      properties:
        title:
          type: string
          example: Updated Report Title
        subject:
          type: string
          example: Updated Subject
        author:
          type: string
          example: Jane Smith
        keywords:
          type: string
          example: updated, keywords
    Range:
      type: object
      description: Represents a contiguous area in a document.
      properties:
        text:
          type: string
          description: Text content of the range.
          example: inserted text content
        style:
          type: string
          description: Style applied to the range.
          example: Normal
        isEmpty:
          type: boolean
          description: Whether the range is empty.
          example: false
    RangeCollection:
      type: object
      description: Collection of ranges.
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/Range'
    SearchRequest:
      type: object
      description: Request to search document content.
      required:
        - searchText
      properties:
        searchText:
          type: string
          description: Text to search for in the document.
          example: quarterly report
        ignorePunct:
          type: boolean
          description: Whether to ignore punctuation.
          example: true
        ignoreSpace:
          type: boolean
          description: Whether to ignore whitespace.
          example: true
        matchCase:
          type: boolean
          description: Whether to perform case-sensitive search.
          example: false
        matchWholeWord:
          type: boolean
          description: Whether to match whole words only.
          example: false
        matchWildcards:
          type: boolean
          description: Whether to use wildcard matching.
          example: false
    Style:
      type: object
      description: Represents a document style.
      properties:
        name:
          type: string
          description: Name of the style.
          example: Heading 1
        type:
          type: string
          description: Style type (Character, Paragraph, Table, List).
          example: Paragraph
        builtIn:
          type: boolean
          description: Whether the style is a built-in style.
          example: true
    StyleCollection:
      type: object
      description: Collection of styles.
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/Style'
    ErrorResponse:
      type: object
      description: Error response from the API.
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Error code.
              example: InvalidArgument
            message:
              type: string
              description: Human-readable error message.
              example: The argument is invalid or missing.