openapi: 3.0.3
info:
  title: Microsoft Graph Visio API
  description: >-
    REST API for accessing and interacting with Visio files stored in SharePoint
    Online and OneDrive for Business through Microsoft Graph. Provides operations
    for reading pages, shapes, shape data, comments, and hyperlinks from Visio diagrams.
  version: 1.0.0
  contact:
    name: Microsoft Graph Support
    url: https://developer.microsoft.com/graph/support
  license:
    name: Microsoft API Terms of Use
    url: https://learn.microsoft.com/en-us/legal/microsoft-apis/terms-of-use
  x-generated-from: documentation
  x-last-validated: '2026-04-18'
servers:
  - url: https://graph.microsoft.com/v1.0
    description: Microsoft Graph v1.0 production endpoint
security:
  - oauth2:
      - Files.Read
      - Files.ReadWrite
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authorization using Microsoft Identity Platform
      flows:
        authorizationCode:
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
          tokenUrl: https://login.microsoftonline.com/common/oauth2/v2.0/token
          scopes:
            Files.Read: Read user files
            Files.ReadWrite: Read and write user files
  schemas:
    VisioDocument:
      type: object
      description: Represents a Visio document.
      properties:
        id:
          type: string
          description: Unique identifier for the document.
          example: doc-abc123
        name:
          type: string
          description: The name of the document.
          example: NetworkDiagram.vsdx
        pages:
          type: array
          description: Collection of pages in the document.
          items:
            $ref: '#/components/schemas/VisioPage'
    VisioPage:
      type: object
      description: Represents a page in a Visio document.
      properties:
        id:
          type: string
          description: Unique identifier for the page.
          example: page-001
        name:
          type: string
          description: The name of the page.
          example: Page-1
        index:
          type: integer
          description: Zero-based index of the page.
          example: 0
        height:
          type: number
          format: double
          description: Height of the page in points.
          example: 792.0
        width:
          type: number
          format: double
          description: Width of the page in points.
          example: 612.0
    PageCollection:
      type: object
      description: Collection of Visio pages.
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/VisioPage'
    VisioShape:
      type: object
      description: Represents a shape on a Visio page.
      properties:
        id:
          type: string
          description: Unique identifier for the shape.
          example: shape-001
        name:
          type: string
          description: The name of the shape.
          example: Server
        text:
          type: string
          description: The text content of the shape.
          example: Web Server 01
        type:
          type: string
          description: The shape type.
          example: GenericShape
    ShapeCollection:
      type: object
      description: Collection of shapes.
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/VisioShape'
    ShapeDataItem:
      type: object
      description: Represents a data item associated with a shape.
      properties:
        label:
          type: string
          description: Label of the data item.
          example: IP Address
        value:
          type: string
          description: Value of the data item.
          example: 10.0.1.100
        format:
          type: string
          description: Format of the data item.
          example: string
    ShapeDataItemCollection:
      type: object
      description: Collection of shape data items.
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/ShapeDataItem'
    VisioComment:
      type: object
      description: Represents a comment on a shape.
      properties:
        id:
          type: string
          description: Unique identifier for the comment.
          example: comment-001
        text:
          type: string
          description: The comment text.
          example: This server needs to be upgraded.
        author:
          type: string
          description: The author of the comment.
          example: Jane Smith
        date:
          type: string
          format: date-time
          description: When the comment was created.
          example: '2026-04-18T10:00:00Z'
    CommentCollection:
      type: object
      description: Collection of comments.
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/VisioComment'
    VisioHyperlink:
      type: object
      description: Represents a hyperlink associated with a shape.
      properties:
        id:
          type: string
          description: Unique identifier for the hyperlink.
          example: hyperlink-001
        address:
          type: string
          format: uri
          description: The URL target of the hyperlink.
          example: https://contoso.com/wiki/server-01
        description:
          type: string
          description: Description of the hyperlink.
          example: Server documentation page
        subAddress:
          type: string
          description: Sub-address target within the document.
          example: ''
    HyperlinkCollection:
      type: object
      description: Collection of hyperlinks.
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/VisioHyperlink'
    ErrorResponse:
      type: object
      description: Error response from the API.
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: ItemNotFound
            message:
              type: string
              example: The specified resource was not found.
tags:
  - name: Documents
    description: Operations for Visio document metadata.
  - name: Pages
    description: Operations for managing pages in Visio documents.
  - name: Shapes
    description: Operations for managing shapes on pages.
  - name: Shape Data
    description: Operations for reading shape data items.
  - name: Comments
    description: Operations for reading and managing shape comments.
  - name: Hyperlinks
    description: Operations for reading shape hyperlinks.
paths:
  /me/drive/items/{item-id}/workbook:
    get:
      operationId: getVisioDocument
      summary: Microsoft Visio Get Document
      description: Retrieve metadata for a Visio document stored in OneDrive or SharePoint.
      tags:
        - Documents
      parameters:
        - name: item-id
          in: path
          required: true
          description: The ID of the Visio file in OneDrive.
          schema:
            type: string
      responses:
        '200':
          description: Document metadata returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VisioDocument'
              examples:
                GetVisioDocument200Example:
                  summary: Default getVisioDocument 200 response
                  x-microcks-default: true
                  value:
                    id: doc-abc123
                    name: NetworkDiagram.vsdx
        '401':
          description: Unauthorized.
        '404':
          description: Document not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /me/drive/items/{item-id}/workbook/pages:
    get:
      operationId: listPages
      summary: Microsoft Visio List Pages
      description: Retrieve a list of pages in the Visio document.
      tags:
        - Pages
      parameters:
        - name: item-id
          in: path
          required: true
          description: The ID of the Visio file.
          schema:
            type: string
      responses:
        '200':
          description: Pages returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageCollection'
              examples:
                ListPages200Example:
                  summary: Default listPages 200 response
                  x-microcks-default: true
                  value:
                    value:
                      - id: page-001
                        name: Page-1
                        index: 0
                        height: 792.0
                        width: 612.0
        '401':
          description: Unauthorized.
        '404':
          description: Document not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /me/drive/items/{item-id}/workbook/pages/{page-id}:
    get:
      operationId: getPage
      summary: Microsoft Visio Get Page
      description: Retrieve a specific page from the Visio document.
      tags:
        - Pages
      parameters:
        - name: item-id
          in: path
          required: true
          description: The ID of the Visio file.
          schema:
            type: string
        - name: page-id
          in: path
          required: true
          description: The ID of the page.
          schema:
            type: string
      responses:
        '200':
          description: Page returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VisioPage'
              examples:
                GetPage200Example:
                  summary: Default getPage 200 response
                  x-microcks-default: true
                  value:
                    id: page-001
                    name: Page-1
                    index: 0
                    height: 792.0
                    width: 612.0
        '401':
          description: Unauthorized.
        '404':
          description: Page not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /me/drive/items/{item-id}/workbook/pages/{page-id}/shapes:
    get:
      operationId: listShapes
      summary: Microsoft Visio List Shapes
      description: Retrieve a list of shapes on a page.
      tags:
        - Shapes
      parameters:
        - name: item-id
          in: path
          required: true
          description: The ID of the Visio file.
          schema:
            type: string
        - name: page-id
          in: path
          required: true
          description: The ID of the page.
          schema:
            type: string
      responses:
        '200':
          description: Shapes returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShapeCollection'
              examples:
                ListShapes200Example:
                  summary: Default listShapes 200 response
                  x-microcks-default: true
                  value:
                    value:
                      - id: shape-001
                        name: Server
                        text: Web Server 01
                        type: GenericShape
        '401':
          description: Unauthorized.
        '404':
          description: Page not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /me/drive/items/{item-id}/workbook/pages/{page-id}/shapes/{shape-id}:
    get:
      operationId: getShape
      summary: Microsoft Visio Get Shape
      description: Retrieve a specific shape from a page.
      tags:
        - Shapes
      parameters:
        - name: item-id
          in: path
          required: true
          description: The ID of the Visio file.
          schema:
            type: string
        - name: page-id
          in: path
          required: true
          description: The ID of the page.
          schema:
            type: string
        - name: shape-id
          in: path
          required: true
          description: The ID of the shape.
          schema:
            type: string
      responses:
        '200':
          description: Shape returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VisioShape'
        '401':
          description: Unauthorized.
        '404':
          description: Shape not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /me/drive/items/{item-id}/workbook/pages/{page-id}/shapes/{shape-id}/shapeDataItems:
    get:
      operationId: listShapeDataItems
      summary: Microsoft Visio List Shape Data Items
      description: Retrieve data items associated with a shape.
      tags:
        - Shape Data
      parameters:
        - name: item-id
          in: path
          required: true
          description: The ID of the Visio file.
          schema:
            type: string
        - name: page-id
          in: path
          required: true
          description: The ID of the page.
          schema:
            type: string
        - name: shape-id
          in: path
          required: true
          description: The ID of the shape.
          schema:
            type: string
      responses:
        '200':
          description: Shape data items returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShapeDataItemCollection'
              examples:
                ListShapeDataItems200Example:
                  summary: Default listShapeDataItems 200 response
                  x-microcks-default: true
                  value:
                    value:
                      - label: IP Address
                        value: 10.0.1.100
                        format: string
        '401':
          description: Unauthorized.
        '404':
          description: Shape not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /me/drive/items/{item-id}/workbook/pages/{page-id}/shapes/{shape-id}/comments:
    get:
      operationId: listShapeComments
      summary: Microsoft Visio List Shape Comments
      description: Retrieve comments associated with a shape.
      tags:
        - Comments
      parameters:
        - name: item-id
          in: path
          required: true
          description: The ID of the Visio file.
          schema:
            type: string
        - name: page-id
          in: path
          required: true
          description: The ID of the page.
          schema:
            type: string
        - name: shape-id
          in: path
          required: true
          description: The ID of the shape.
          schema:
            type: string
      responses:
        '200':
          description: Comments returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentCollection'
              examples:
                ListShapeComments200Example:
                  summary: Default listShapeComments 200 response
                  x-microcks-default: true
                  value:
                    value:
                      - id: comment-001
                        text: This server needs to be upgraded.
                        author: Jane Smith
                        date: '2026-04-18T10:00:00Z'
        '401':
          description: Unauthorized.
        '404':
          description: Shape not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /me/drive/items/{item-id}/workbook/pages/{page-id}/shapes/{shape-id}/hyperlinks:
    get:
      operationId: listShapeHyperlinks
      summary: Microsoft Visio List Shape Hyperlinks
      description: Retrieve hyperlinks associated with a shape.
      tags:
        - Hyperlinks
      parameters:
        - name: item-id
          in: path
          required: true
          description: The ID of the Visio file.
          schema:
            type: string
        - name: page-id
          in: path
          required: true
          description: The ID of the page.
          schema:
            type: string
        - name: shape-id
          in: path
          required: true
          description: The ID of the shape.
          schema:
            type: string
      responses:
        '200':
          description: Hyperlinks returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HyperlinkCollection'
              examples:
                ListShapeHyperlinks200Example:
                  summary: Default listShapeHyperlinks 200 response
                  x-microcks-default: true
                  value:
                    value:
                      - id: hyperlink-001
                        address: https://contoso.com/wiki/server-01
                        description: Server documentation page
                        subAddress: ''
        '401':
          description: Unauthorized.
        '404':
          description: Shape not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK