Tableau Workbooks API

openapi: 3.1.0
info:
  version: 3.24.0
  title: Tableau REST Authentication Workbooks API
  description: The Tableau REST API allows you to manage and change Tableau Server and Tableau Cloud resources programmatically using HTTP. You can use the REST API to manage sites, projects, workbooks, views, data sources, users, groups, permissions, schedules, subscriptions, and more.
  license:
    name: Proprietary
    url: https://www.tableau.com/legal
  termsOfService: https://www.tableau.com/legal
  contact:
    name: Tableau Developer Support
    url: https://www.tableau.com/support
servers:
- url: https://{server}/api/{api-version}
  description: Tableau Server or Tableau Cloud
  variables:
    server:
      default: 10ax.online.tableau.com
      description: The hostname of your Tableau Server or Tableau Cloud site. For Tableau Cloud, use the pod URL (e.g., 10ax.online.tableau.com). For Tableau Server, use your server hostname.
    api-version:
      default: '3.24'
      description: The version of the REST API to use. The API version corresponds to the version of Tableau Server or Tableau Cloud.
      enum:
      - '3.24'
      - '3.23'
      - '3.22'
      - '3.21'
      - '3.20'
      - '3.19'
security:
- TableauAuth: []
tags:
- name: Workbooks
  description: Publish, query, update, delete, and download workbooks. Workbooks contain one or more views (sheets, dashboards, or stories) and can connect to one or more data sources.
paths:
  /sites/{site-id}/workbooks:
    get:
      operationId: queryWorkbooksForSite
      summary: Tableau Query Workbooks for Site
      description: Returns the workbooks on a site. If the user is not an administrator, the method returns just the workbooks that the user has permissions to view.
      tags:
      - Workbooks
      parameters:
      - $ref: '#/components/parameters/SiteId'
      - $ref: '#/components/parameters/PageSize'
      - $ref: '#/components/parameters/PageNumber'
      - $ref: '#/components/parameters/Filter'
      - $ref: '#/components/parameters/Sort'
      - $ref: '#/components/parameters/Fields'
      responses:
        '200':
          description: A paginated list of workbooks.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkbookListResponse'
              examples:
                Queryworkbooksforsite200Example:
                  summary: Default queryWorkbooksForSite 200 response
                  x-microcks-default: true
                  value:
                    pagination:
                      pageNumber: 10
                      pageSize: 10
                      totalAvailable: 10
                    workbooks:
                      workbook:
                      - {}
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /sites/{site-id}/workbooks/{workbook-id}:
    get:
      operationId: queryWorkbook
      summary: Tableau Query Workbook
      description: Returns information about the specified workbook, including information about views and tags.
      tags:
      - Workbooks
      parameters:
      - $ref: '#/components/parameters/SiteId'
      - $ref: '#/components/parameters/WorkbookId'
      responses:
        '200':
          description: Workbook details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkbookResponse'
              examples:
                Queryworkbook200Example:
                  summary: Default queryWorkbook 200 response
                  x-microcks-default: true
                  value:
                    workbook:
                      id: abc123
                      name: Example Title
                      description: A sample description.
                      contentUrl: https://www.example.com
                      webpageUrl: https://www.example.com
                      showTabs: true
                      size: 10
                      createdAt: '2026-01-15T10:30:00Z'
                      updatedAt: '2026-01-15T10:30:00Z'
                      encryptExtracts: example_value
                      defaultViewId: '500123'
                      project:
                        id: abc123
                        name: Example Title
                      owner:
                        id: abc123
                        name: Example Title
                      tags:
                        tag: {}
                      views:
                        view: {}
                      usage:
                        totalViewCount: 10
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateWorkbook
      summary: Tableau Update Workbook
      description: Modifies an existing workbook, allowing you to change the owner, project, or other properties.
      tags:
      - Workbooks
      parameters:
      - $ref: '#/components/parameters/SiteId'
      - $ref: '#/components/parameters/WorkbookId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWorkbookRequest'
            examples:
              UpdateworkbookRequestExample:
                summary: Default updateWorkbook request
                x-microcks-default: true
                value:
                  workbook:
                    name: Example Title
                    showTabs: true
                    project:
                      id: abc123
                    owner:
                      id: abc123
                    encryptExtracts: example_value
      responses:
        '200':
          description: Workbook was updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkbookResponse'
              examples:
                Updateworkbook200Example:
                  summary: Default updateWorkbook 200 response
                  x-microcks-default: true
                  value:
                    workbook:
                      id: abc123
                      name: Example Title
                      description: A sample description.
                      contentUrl: https://www.example.com
                      webpageUrl: https://www.example.com
                      showTabs: true
                      size: 10
                      createdAt: '2026-01-15T10:30:00Z'
                      updatedAt: '2026-01-15T10:30:00Z'
                      encryptExtracts: example_value
                      defaultViewId: '500123'
                      project:
                        id: abc123
                        name: Example Title
                      owner:
                        id: abc123
                        name: Example Title
                      tags:
                        tag: {}
                      views:
                        view: {}
                      usage:
                        totalViewCount: 10
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteWorkbook
      summary: Tableau Delete Workbook
      description: Deletes a workbook. When a workbook is deleted, all of its assets are also deleted, including associated views.
      tags:
      - Workbooks
      parameters:
      - $ref: '#/components/parameters/SiteId'
      - $ref: '#/components/parameters/WorkbookId'
      responses:
        '204':
          description: Workbook was deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /sites/{site-id}/workbooks/{workbook-id}/connections:
    get:
      operationId: queryWorkbookConnections
      summary: Tableau Query Workbook Connections
      description: Returns a list of data connections for the specified workbook.
      tags:
      - Workbooks
      parameters:
      - $ref: '#/components/parameters/SiteId'
      - $ref: '#/components/parameters/WorkbookId'
      responses:
        '200':
          description: A list of data connections for the workbook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionListResponse'
              examples:
                Queryworkbookconnections200Example:
                  summary: Default queryWorkbookConnections 200 response
                  x-microcks-default: true
                  value:
                    connections:
                      connection:
                      - {}
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /sites/{site-id}/workbooks/{workbook-id}/content:
    get:
      operationId: downloadWorkbook
      summary: Tableau Download Workbook
      description: Downloads a workbook in .twb or .twbx format. If the workbook contains extracts, the download is in .twbx format.
      tags:
      - Workbooks
      parameters:
      - $ref: '#/components/parameters/SiteId'
      - $ref: '#/components/parameters/WorkbookId'
      - name: extractValue
        in: query
        schema:
          type: boolean
          default: true
        description: If true, and the workbook contains extracts, the download includes the extracts.
        example: true
      responses:
        '200':
          description: The workbook file.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
              examples:
                Downloadworkbook200Example:
                  summary: Default downloadWorkbook 200 response
                  x-microcks-default: true
                  value: example_value
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /sites/{site-id}/workbooks/{workbook-id}/previewImage:
    get:
      operationId: queryWorkbookPreviewImage
      summary: Tableau Query Workbook Preview Image
      description: Returns the thumbnail image for the specified workbook as a PNG file.
      tags:
      - Workbooks
      parameters:
      - $ref: '#/components/parameters/SiteId'
      - $ref: '#/components/parameters/WorkbookId'
      responses:
        '200':
          description: A PNG preview image of the workbook.
          content:
            image/png:
              schema:
                type: string
                format: binary
              examples:
                Queryworkbookpreviewimage200Example:
                  summary: Default queryWorkbookPreviewImage 200 response
                  x-microcks-default: true
                  value: example_value
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /sites/{site-id}/workbooks/{workbook-id}/views:
    get:
      operationId: queryViewsForWorkbook
      summary: Tableau Query Views for Workbook
      description: Returns all the views for the specified workbook, optionally including usage statistics.
      tags:
      - Workbooks
      parameters:
      - $ref: '#/components/parameters/SiteId'
      - $ref: '#/components/parameters/WorkbookId'
      - name: includeUsageStatistics
        in: query
        schema:
          type: boolean
          default: false
        description: If true, returns usage statistics for each view.
        example: true
      responses:
        '200':
          description: A list of views for the workbook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ViewListResponse'
              examples:
                Queryviewsforworkbook200Example:
                  summary: Default queryViewsForWorkbook 200 response
                  x-microcks-default: true
                  value:
                    pagination:
                      pageNumber: 10
                      pageSize: 10
                      totalAvailable: 10
                    views:
                      view:
                      - {}
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /sites/{site-id}/workbooks/{workbook-id}/publish:
    post:
      operationId: publishWorkbook
      summary: Tableau Publish Workbook
      description: Publishes a workbook on the specified site. To make changes to an existing workbook, call Update Workbook or Publish Workbook with overwrite set to true.
      tags:
      - Workbooks
      parameters:
      - $ref: '#/components/parameters/SiteId'
      - name: overwrite
        in: query
        schema:
          type: boolean
          default: false
        description: If true, overwrites an existing workbook with the same name in the same project.
        example: true
      - name: skipConnectionCheck
        in: query
        schema:
          type: boolean
          default: false
        description: If true, skips the connection check during publish.
        example: true
      requestBody:
        required: true
        content:
          multipart/mixed:
            schema:
              type: object
              properties:
                request_payload:
                  $ref: '#/components/schemas/PublishWorkbookRequest'
                tableau_workbook:
                  type: string
                  format: binary
                  description: The workbook file (.twb or .twbx).
            examples:
              PublishworkbookRequestExample:
                summary: Default publishWorkbook request
                x-microcks-default: true
                value:
                  request_payload:
                    workbook:
                      name: Example Title
                      description: A sample description.
                      showTabs: true
                      project:
                        id: abc123
                      connections:
                        connection: {}
                  tableau_workbook: example_value
      responses:
        '201':
          description: Workbook was published successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkbookResponse'
              examples:
                Publishworkbook201Example:
                  summary: Default publishWorkbook 201 response
                  x-microcks-default: true
                  value:
                    workbook:
                      id: abc123
                      name: Example Title
                      description: A sample description.
                      contentUrl: https://www.example.com
                      webpageUrl: https://www.example.com
                      showTabs: true
                      size: 10
                      createdAt: '2026-01-15T10:30:00Z'
                      updatedAt: '2026-01-15T10:30:00Z'
                      encryptExtracts: example_value
                      defaultViewId: '500123'
                      project:
                        id: abc123
                        name: Example Title
                      owner:
                        id: abc123
                        name: Example Title
                      tags:
                        tag: {}
                      views:
                        view: {}
                      usage:
                        totalViewCount: 10
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /sites/{site-id}/workbooks/{workbook-id}/tags:
    get:
      operationId: queryWorkbookTags
      summary: Tableau Query Workbook Tags
      description: Returns a list of tags that have been added to the specified workbook.
      tags:
      - Workbooks
      parameters:
      - $ref: '#/components/parameters/SiteId'
      - $ref: '#/components/parameters/WorkbookId'
      responses:
        '200':
          description: A list of tags on the workbook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagListResponse'
              examples:
                Queryworkbooktags200Example:
                  summary: Default queryWorkbookTags 200 response
                  x-microcks-default: true
                  value:
                    tags:
                      tag:
                      - {}
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: addTagsToWorkbook
      summary: Tableau Add Tags to Workbook
      description: Adds one or more tags to the specified workbook.
      tags:
      - Workbooks
      parameters:
      - $ref: '#/components/parameters/SiteId'
      - $ref: '#/components/parameters/WorkbookId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TagListRequest'
            examples:
              AddtagstoworkbookRequestExample:
                summary: Default addTagsToWorkbook request
                x-microcks-default: true
                value:
                  tags:
                    tag:
                    - {}
      responses:
        '200':
          description: Tags were added successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagListResponse'
              examples:
                Addtagstoworkbook200Example:
                  summary: Default addTagsToWorkbook 200 response
                  x-microcks-default: true
                  value:
                    tags:
                      tag:
                      - {}
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /sites/{site-id}/workbooks/{workbook-id}/tags/{tag-name}:
    delete:
      operationId: deleteTagFromWorkbook
      summary: Tableau Delete Tag From Workbook
      description: Deletes a tag from the specified workbook.
      tags:
      - Workbooks
      parameters:
      - $ref: '#/components/parameters/SiteId'
      - $ref: '#/components/parameters/WorkbookId'
      - name: tag-name
        in: path
        required: true
        schema:
          type: string
        description: The name of the tag to delete.
        example: example_value
      responses:
        '204':
          description: Tag was deleted successfully.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /sites/{site-id}/workbooks/{workbook-id}/revisions:
    get:
      operationId: getWorkbookRevisions
      summary: Tableau Get Workbook Revisions
      description: Returns a list of revision information (revision number, published date, and other metadata) for each revision of the specified workbook.
      tags:
      - Workbooks
      parameters:
      - $ref: '#/components/parameters/SiteId'
      - $ref: '#/components/parameters/WorkbookId'
      - $ref: '#/components/parameters/PageSize'
      - $ref: '#/components/parameters/PageNumber'
      responses:
        '200':
          description: A list of workbook revisions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RevisionListResponse'
              examples:
                Getworkbookrevisions200Example:
                  summary: Default getWorkbookRevisions 200 response
                  x-microcks-default: true
                  value:
                    pagination:
                      pageNumber: 10
                      pageSize: 10
                      totalAvailable: 10
                    revisions:
                      revision:
                      - {}
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /sites/{site-id}/users/{user-id}/workbooks:
    get:
      operationId: queryWorkbooksForUser
      summary: Tableau Query Workbooks for User
      description: Returns the workbooks that the specified user owns or has Read (view) permissions for.
      tags:
      - Workbooks
      parameters:
      - $ref: '#/components/parameters/SiteId'
      - $ref: '#/components/parameters/UserId'
      - $ref: '#/components/parameters/PageSize'
      - $ref: '#/components/parameters/PageNumber'
      responses:
        '200':
          description: A paginated list of workbooks for the user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkbookListResponse'
              examples:
                Queryworkbooksforuser200Example:
                  summary: Default queryWorkbooksForUser 200 response
                  x-microcks-default: true
                  value:
                    pagination:
                      pageNumber: 10
                      pageSize: 10
                      totalAvailable: 10
                    workbooks:
                      workbook:
                      - {}
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /sites/{site-id}/workbooks/{workbook-id}/permissions:
    get:
      operationId: queryWorkbookPermissions
      summary: Tableau Query Workbook Permissions
      description: Returns a list of permissions for the specified workbook.
      tags:
      - Workbooks
      parameters:
      - $ref: '#/components/parameters/SiteId'
      - $ref: '#/components/parameters/WorkbookId'
      responses:
        '200':
          description: A list of permissions on the workbook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PermissionListResponse'
              examples:
                Queryworkbookpermissions200Example:
                  summary: Default queryWorkbookPermissions 200 response
                  x-microcks-default: true
                  value:
                    permissions:
                      granteeCapabilities:
                      - {}
                    parent:
                      project:
                        id: abc123
                        name: Example Title
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: addWorkbookPermissions
      summary: Tableau Add Workbook Permissions
      description: Adds permissions to the specified workbook for a user or group.
      tags:
      - Workbooks
      parameters:
      - $ref: '#/components/parameters/SiteId'
      - $ref: '#/components/parameters/WorkbookId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddPermissionsRequest'
            examples:
              AddworkbookpermissionsRequestExample:
                summary: Default addWorkbookPermissions request
                x-microcks-default: true
                value:
                  permissions:
                    granteeCapabilities:
                    - {}
      responses:
        '200':
          description: Permissions were added successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PermissionListResponse'
              examples:
                Addworkbookpermissions200Example:
                  summary: Default addWorkbookPermissions 200 response
                  x-microcks-default: true
                  value:
                    permissions:
                      granteeCapabilities:
                      - {}
                    parent:
                      project:
                        id: abc123
                        name: Example Title
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  parameters:
    PageSize:
      name: pageSize
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 1000
        default: 100
      description: The number of items to return in one response. The minimum is 1 and the maximum is 1000.
    Filter:
      name: filter
      in: query
      schema:
        type: string
      description: An expression that lets you specify a subset of items to return. Use the format filter=field:operator:value. Operators include eq, gt, gte, lt, lte, has, and in.
    UserId:
      name: user-id
      in: path
      required: true
      schema:
        type: string
      description: The ID of the user.
    Fields:
      name: fields
      in: query
      schema:
        type: string
      description: An expression that lets you specify which fields are included in the response. Use the format fields=field1,field2. Use _default_ to return the default set of fields, or _all_ to return all fields.
    PageNumber:
      name: pageNumber
      in: query
      schema:
        type: integer
        minimum: 1
        default: 1
      description: The page number of the set of items to return. The default is 1.
    SiteId:
      name: site-id
      in: path
      required: true
      schema:
        type: string
      description: The ID of the site. You can get the site ID from the response to the Sign In method.
    WorkbookId:
      name: workbook-id
      in: path
      required: true
      schema:
        type: string
      description: The ID of the workbook.
    Sort:
      name: sort
      in: query
      schema:
        type: string
      description: An expression that lets you specify the order in which items are returned. Use the format sort=field:direction where direction is asc or desc.
  schemas:
    PublishWorkbookRequest:
      type: object
      properties:
        workbook:
          type: object
          required:
          - name
          - project
          properties:
            name:
              type: string
              description: The name of the workbook.
            description:
              type: string
              description: A description of the workbook.
            showTabs:
              type: boolean
              description: Whether to show views as tabs.
            project:
              type: object
              required:
              - id
              properties:
                id:
                  type: string
                  description: The ID of the project to publish to.
            connections:
              type: object
              properties:
                connection:
                  type: array
                  items:
                    type: object
                    properties:
                      serverAddress:
                        type: string
                      serverPort:
                        type: string
                      credentials:
                        type: object
                        properties:
                          name:
                            type: string
                          password:
                            type: string
                            format: password
                          embed:
                            type: boolean
          example: example_value
    AddPermissionsRequest:
      type: object
      properties:
        permissions:
          $ref: '#/components/schemas/Permission'
    PermissionListResponse:
      type: object
      properties:
        permissions:
          $ref: '#/components/schemas/Permission'
        parent:
          type: object
          properties:
            project:
              type: object
              properties:
                id:
                  type: string
                name:
                  type: string
          example: example_value
    Connection:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the connection.
          example: abc123
        type:
          type: string
          description: The type of connection (e.g., sqlserver, postgres).
          example: example_value
        serverAddress:
          type: string
          description: The address of the server for the connection.
          example: example_value
        serverPort:
          type: string
          description: The port used for the connection.
          example: example_value
        userName:
          type: string
          description: The user name for the connection.
          example: example_value
        datasource:
          type: object
          properties:
            id:
              type: string
              description: The ID of the associated data source.
            name:
              type: string
              description: The name of the associated data source.
          example: example_value
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            summary:
              type: string
              description: A short summary of the error.
            detail:
              type: string
              description: A detailed description of the error.
            code:
              type: string
              description: A numeric error code.
          example: example_value
    ViewListResponse:
      type: object
      properties:
        pagination:
          $ref: '#/components/schemas/Pagination'
        views:
          type: object
          properties:
            view:
              type: array
              items:
                $ref: '#/components/schemas/View'
          example: example_value
    Tag:
      type: object
      properties:
        label:
          type: string
          description: The text of the tag.
          example: Example Title
    Pagination:
      type: object
      properties:
        pageNumber:
          type: integer
          description: The current page number.
          example: 10
        pageSize:
          type: integer
          description: The number of items per page.
          example: 10
        totalAvailable:
          type: integer
          description: The total number of items available.
          example: 10
    Workbook:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the workbook.
          example: abc123
        name:
          type: string
          description: The name of the workbook.
          example: Example Title
        description:
          type: string
          description: A description of the workbook.
          example: A sample description.
        contentUrl:
          type: string
          description: The URL name of the workbook, used in URLs to access the workbook.
          example: https://www.example.com
        webpageUrl:
          type: string
          format: uri
          description: The full URL to the workbook on the server.
          example: https://www.example.com
        showTabs:
          type: boolean
          description: Whether the workbook shows views as tabs.
          example: true
        size:
          type: integer
          description: The size of the workbook in bytes.
          example: 10
        createdAt:
          type: string


# --- truncated at 32 KB (42 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tableau/refs/heads/main/openapi/tableau-workbooks-api-openapi.yml