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: [email protected]
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.