Visio JavaScript API

openapi: 3.1.0
info:
  title: Visio JavaScript API
  description: >-
    The Visio JavaScript API enables building Office Add-ins that interact with
    Visio diagrams embedded in classic SharePoint Online pages. The API provides
    access to document elements including pages, shapes, hyperlinks, comments,
    shape data items, and shape views. Developers can create visual overlays,
    register mouse event handlers, read shape text and shape data, and control
    application settings. The API uses a request context and proxy object pattern
    with batch execution via Visio.run() and context.sync().
  version: '1.1'
  contact:
    name: Microsoft Office Dev
    url: https://developer.microsoft.com/office
    email: [email protected]
  license:
    name: Microsoft APIs Terms of Use
    url: https://learn.microsoft.com/en-us/legal/microsoft-apis/terms-of-use
  termsOfService: https://www.microsoft.com/en-us/legal/terms-of-use
externalDocs:
  description: Visio JavaScript API Documentation
  url: https://learn.microsoft.com/en-us/office/dev/add-ins/visio/visio-overview
servers:
  - url: https://appsforoffice.microsoft.com/embedded/1.0
    description: Visio Office Add-ins embedded endpoint
tags:
  - name: Documents
    description: Operations for accessing and managing Visio document properties and views
  - name: Pages
    description: Operations for listing and managing pages within a Visio document
  - name: Shapes
    description: Operations for accessing and managing shapes on a Visio page
  - name: Shape Data
    description: Operations for reading structured data associated with shapes
  - name: Hyperlinks
    description: Operations for accessing hyperlinks attached to shapes
  - name: Comments
    description: Operations for reading and managing shape comments
  - name: Application
    description: Operations for controlling the Visio application host settings
security:
  - EmbeddedSession: []
paths:
  /document:
    get:
      operationId: getDocument
      summary: Get Document
      description: >-
        Returns the current Visio document loaded in the embedded session,
        including its properties and view settings.
      tags:
        - Documents
      responses:
        '200':
          description: Document object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '401':
          description: Unauthorized - Invalid or missing EmbeddedSession
        '500':
          description: Internal server error
  /document/pages:
    get:
      operationId: listPages
      summary: List Pages
      description: >-
        Returns all pages in the current Visio document. Each page includes its
        name, index, background status, and view settings.
      tags:
        - Pages
      responses:
        '200':
          description: Collection of pages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageCollection'
        '401':
          description: Unauthorized
        '500':
          description: Internal server error
  /document/pages/{pageName}:
    get:
      operationId: getPage
      summary: Get Page
      description: >-
        Returns a specific page from the Visio document by its name. Includes
        page properties, view configuration, and associated shapes.
      tags:
        - Pages
      parameters:
        - name: pageName
          in: path
          required: true
          description: Name of the Visio page to retrieve
          schema:
            type: string
      responses:
        '200':
          description: Page object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page'
        '404':
          description: Page not found
        '500':
          description: Internal server error
  /document/pages/{pageName}/shapes:
    get:
      operationId: listShapes
      summary: List Shapes
      description: >-
        Returns all shapes on the specified Visio page. Each shape includes its
        name, text, ID, selection state, bounding box, and associated data.
      tags:
        - Shapes
      parameters:
        - name: pageName
          in: path
          required: true
          description: Name of the Visio page
          schema:
            type: string
      responses:
        '200':
          description: Collection of shapes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShapeCollection'
        '404':
          description: Page not found
        '500':
          description: Internal server error
  /document/pages/{pageName}/shapes/{shapeId}:
    get:
      operationId: getShape
      summary: Get Shape
      description: >-
        Returns a specific shape on the Visio page identified by its shape ID.
        Includes shape text, data items, hyperlinks, and visual view properties.
      tags:
        - Shapes
      parameters:
        - name: pageName
          in: path
          required: true
          description: Name of the Visio page
          schema:
            type: string
        - name: shapeId
          in: path
          required: true
          description: Numeric ID of the shape
          schema:
            type: integer
      responses:
        '200':
          description: Shape object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shape'
        '404':
          description: Shape not found
        '500':
          description: Internal server error
  /document/pages/{pageName}/shapes/{shapeId}/shapeDataItems:
    get:
      operationId: listShapeDataItems
      summary: List Shape Data Items
      description: >-
        Returns all structured data items associated with a specific shape.
        Shape data items contain label-value pairs that store business data
        linked to diagram elements.
      tags:
        - Shape Data
      parameters:
        - name: pageName
          in: path
          required: true
          description: Name of the Visio page
          schema:
            type: string
        - name: shapeId
          in: path
          required: true
          description: Numeric ID of the shape
          schema:
            type: integer
      responses:
        '200':
          description: Collection of shape data items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShapeDataItemCollection'
        '404':
          description: Shape not found
        '500':
          description: Internal server error
  /document/pages/{pageName}/shapes/{shapeId}/hyperlinks:
    get:
      operationId: listShapeHyperlinks
      summary: List Shape Hyperlinks
      description: >-
        Returns all hyperlinks attached to a specific shape in the Visio diagram.
        Hyperlinks may point to external URLs, other pages, or diagram elements.
      tags:
        - Hyperlinks
      parameters:
        - name: pageName
          in: path
          required: true
          description: Name of the Visio page
          schema:
            type: string
        - name: shapeId
          in: path
          required: true
          description: Numeric ID of the shape
          schema:
            type: integer
      responses:
        '200':
          description: Collection of hyperlinks
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HyperlinkCollection'
        '404':
          description: Shape not found
        '500':
          description: Internal server error
  /document/pages/{pageName}/shapes/{shapeId}/comments:
    get:
      operationId: listShapeComments
      summary: List Shape Comments
      description: >-
        Returns all comments attached to a specific shape in the Visio diagram.
        Comments contain author, date, and text content.
      tags:
        - Comments
      parameters:
        - name: pageName
          in: path
          required: true
          description: Name of the Visio page
          schema:
            type: string
        - name: shapeId
          in: path
          required: true
          description: Numeric ID of the shape
          schema:
            type: integer
      responses:
        '200':
          description: Collection of comments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentCollection'
        '404':
          description: Shape not found
        '500':
          description: Internal server error
  /document/application:
    get:
      operationId: getApplication
      summary: Get Application
      description: >-
        Returns the Visio application host settings for the embedded session,
        including toolbar visibility and other UI configuration options.
      tags:
        - Application
      responses:
        '200':
          description: Application settings object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
        '500':
          description: Internal server error
    patch:
      operationId: updateApplication
      summary: Update Application Settings
      description: >-
        Updates Visio application settings such as toolbar visibility for the
        current embedded session.
      tags:
        - Application
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplicationUpdate'
      responses:
        '200':
          description: Updated application settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
        '400':
          description: Invalid request body
        '500':
          description: Internal server error
  /document/getActivePage:
    get:
      operationId: getActivePage
      summary: Get Active Page
      description: >-
        Returns the currently active page in the Visio document embedded in the
        SharePoint page. Includes all shapes and view configuration for the page.
      tags:
        - Pages
      responses:
        '200':
          description: Active page object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page'
        '500':
          description: Internal server error
  /document/pages/{pageName}/view:
    patch:
      operationId: updatePageView
      summary: Update Page View
      description: >-
        Updates the view settings for a specific Visio page, including zoom level
        and scroll position.
      tags:
        - Pages
      parameters:
        - name: pageName
          in: path
          required: true
          description: Name of the Visio page
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PageViewUpdate'
      responses:
        '200':
          description: Updated page view
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageView'
        '404':
          description: Page not found
        '500':
          description: Internal server error
  /document/pages/{pageName}/shapes/{shapeId}/view:
    patch:
      operationId: updateShapeView
      summary: Update Shape View
      description: >-
        Updates the visual presentation of a shape, including highlight color,
        tooltip text, and overlay content for the specified shape.
      tags:
        - Shapes
      parameters:
        - name: pageName
          in: path
          required: true
          description: Name of the Visio page
          schema:
            type: string
        - name: shapeId
          in: path
          required: true
          description: Numeric ID of the shape
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShapeViewUpdate'
      responses:
        '200':
          description: Updated shape view
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShapeView'
        '404':
          description: Shape not found
        '500':
          description: Internal server error
components:
  securitySchemes:
    EmbeddedSession:
      type: apiKey
      in: header
      name: X-Embedded-Session
      description: Visio EmbeddedSession token obtained via OfficeExtension.EmbeddedSession initialization
  schemas:
    Document:
      type: object
      description: Represents the Visio document loaded in the embedded session
      properties:
        id:
          type: string
          description: Unique identifier for the document
        title:
          type: string
          description: Title of the Visio document
        application:
          $ref: '#/components/schemas/Application'
        view:
          $ref: '#/components/schemas/DocumentView'
    DocumentView:
      type: object
      description: View settings for the Visio document
      properties:
        disableHyperlinks:
          type: boolean
          description: Whether hyperlinks are disabled in the document view
        disablePan:
          type: boolean
          description: Whether panning is disabled
        disableZoom:
          type: boolean
          description: Whether zooming is disabled
        hideDiagramBoundary:
          type: boolean
          description: Whether the diagram boundary is hidden
    Application:
      type: object
      description: Represents the Visio application host settings
      properties:
        showToolbars:
          type: boolean
          description: Whether toolbars are displayed in the Visio application
    ApplicationUpdate:
      type: object
      description: Partial update to application settings
      properties:
        showToolbars:
          type: boolean
          description: Set to false to hide toolbars
    PageCollection:
      type: object
      description: A collection of Visio pages
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Page'
    Page:
      type: object
      description: Represents a page in the Visio document
      properties:
        id:
          type: integer
          description: Numeric page identifier
        name:
          type: string
          description: Name of the page
        index:
          type: integer
          description: Zero-based index of the page in the document
        isBackground:
          type: boolean
          description: Whether this page is a background page
        view:
          $ref: '#/components/schemas/PageView'
        shapes:
          $ref: '#/components/schemas/ShapeCollection'
    PageView:
      type: object
      description: View settings for a Visio page
      properties:
        zoom:
          type: integer
          description: Zoom level as a percentage (e.g. 100 for 100%)
    PageViewUpdate:
      type: object
      description: Partial update to page view settings
      properties:
        zoom:
          type: integer
          description: Zoom level as a percentage
    ShapeCollection:
      type: object
      description: A collection of shapes on a Visio page
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Shape'
    Shape:
      type: object
      description: Represents a shape element on a Visio page
      properties:
        id:
          type: integer
          description: Numeric shape identifier
        name:
          type: string
          description: Name of the shape
        text:
          type: string
          description: Text content displayed inside the shape
        select:
          type: boolean
          description: Whether this shape is currently selected by the user
        view:
          $ref: '#/components/schemas/ShapeView'
        shapeDataItems:
          $ref: '#/components/schemas/ShapeDataItemCollection'
        hyperlinks:
          $ref: '#/components/schemas/HyperlinkCollection'
        comments:
          $ref: '#/components/schemas/CommentCollection'
        boundingBox:
          $ref: '#/components/schemas/BoundingBox'
    ShapeView:
      type: object
      description: Visual presentation settings for a shape
      properties:
        highlight:
          $ref: '#/components/schemas/Highlight'
        tooltip:
          type: string
          description: Tooltip text shown on hover
    ShapeViewUpdate:
      type: object
      description: Partial update to shape view settings
      properties:
        highlight:
          $ref: '#/components/schemas/Highlight'
        tooltip:
          type: string
          description: New tooltip text for the shape
    Highlight:
      type: object
      description: Highlight decoration applied to a shape
      properties:
        color:
          type: string
          description: CSS color string for the highlight (e.g. #FF0000)
        width:
          type: integer
          description: Width of the highlight border in points
    BoundingBox:
      type: object
      description: Bounding box coordinates of a shape
      properties:
        x:
          type: number
          description: X coordinate of the top-left corner
        y:
          type: number
          description: Y coordinate of the top-left corner
        width:
          type: number
          description: Width of the bounding box
        height:
          type: number
          description: Height of the bounding box
    ShapeDataItemCollection:
      type: object
      description: Collection of data items associated with a shape
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ShapeDataItem'
    ShapeDataItem:
      type: object
      description: A structured data item (label-value pair) associated with a shape
      properties:
        label:
          type: string
          description: Label or key for the data item
        value:
          type: string
          description: Value associated with the label
        format:
          type: string
          description: Optional display format for the value
        formattedValue:
          type: string
          description: Value after applying the format string
    HyperlinkCollection:
      type: object
      description: Collection of hyperlinks on a shape
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Hyperlink'
    Hyperlink:
      type: object
      description: A hyperlink attached to a Visio shape
      properties:
        address:
          type: string
          description: URL or file path the hyperlink points to
        description:
          type: string
          description: Display description for the hyperlink
        subAddress:
          type: string
          description: Sub-address within the target (e.g. page name)
        extraInfo:
          type: string
          description: Additional information passed with the URL
    CommentCollection:
      type: object
      description: Collection of comments on a shape
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Comment'
    Comment:
      type: object
      description: A comment associated with a Visio shape
      properties:
        author:
          type: string
          description: Name of the comment author
        date:
          type: string
          format: date-time
          description: Timestamp when the comment was created
        text:
          type: string
          description: Content of the comment
    Error:
      type: object
      description: Error response from the Visio API
      properties:
        code:
          type: string
          description: Error code identifier
          enum:
            - InvalidArgument
            - GeneralException
            - NotImplemented
            - UnsupportedOperation
            - AccessDenied
            - ItemNotFound
        message:
          type: string
          description: Human-readable error message