Confluence Whiteboard API

openapi: 3.2.0
info:
  title: Confluence Cloud REST API v2 Whiteboard API
  description: This document describes Confluence's v2 APIs. This is intended to be an iteration on the existing Confluence Cloud REST API with improvements in both endpoint definitions and performance.
  termsOfService: https://developer.atlassian.com/platform/marketplace/atlassian-developer-terms/
  version: 2.0.0
servers:
- url: https://{your-domain}/wiki/api/v2
  variables:
    your-domain:
      default: no-default
      description: Specific domain of the Confluence site being used. Must be provided.
tags:
- name: Whiteboard
  description: ''
paths:
  /whiteboards:
    post:
      tags:
      - Whiteboard
      operationId: createWhiteboard
      summary: Create whiteboard
      description: 'Creates a whiteboard in the space.


        **Permissions required**:

        Permission to view the corresponding space. Permission to create a whiteboard in the space.'
      parameters:
      - name: private
        in: query
        description: The whiteboard will be private. Only the user who creates this whiteboard will have permission to view and edit one.
        schema:
          type: boolean
          default: false
      requestBody:
        $ref: '#/components/requestBodies/WhiteboardCreateRequest'
      responses:
        '200':
          description: Returned if the whiteboard was successfully created.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/WhiteboardSingle'
                - type: object
                  properties:
                    _links:
                      type: object
                      properties:
                        base:
                          type: string
                          description: Base url of the Confluence site.
        '400':
          description: Returned if an invalid request is provided.
          content: {}
        '401':
          description: Returned if the authentication credentials are incorrect or missing from the request.
          content: {}
        '404':
          description: 'Returned if:

            - The space does not exist

            - The user does not have permissions to view the space

            - The user does not have the needed permissions to create a whiteboard in the provided space'
        '413':
          description: Returned if the request is too large in size (over 5 MB).
          content: {}
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - write:whiteboard:confluence
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - write:whiteboard:confluence
      x-atlassian-connect-scope: WRITE
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: false
  /whiteboards/{id}:
    get:
      tags:
      - Whiteboard
      operationId: getWhiteboardById
      summary: Get whiteboard by id
      description: 'Returns a specific whiteboard.


        **Permissions required**:

        Permission to view the whiteboard and its corresponding space.'
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the whiteboard to be returned
        schema:
          format: int64
          type: integer
      - name: include-collaborators
        in: query
        description: Includes collaborators on the whiteboard.
        schema:
          type: boolean
          default: false
      - name: include-direct-children
        in: query
        description: Includes direct children of the whiteboard, as defined in the `ChildrenResponse` object.
        schema:
          type: boolean
          default: false
      - name: include-operations
        in: query
        description: 'Includes operations associated with this whiteboard in the response, as defined in the `Operation` object.

          The number of results will be limited to 50 and sorted in the default sort order.

          A `meta` and `_links` property will be present to indicate if more results are available and a link to retrieve the rest of the results.'
        schema:
          type: boolean
          default: false
      - name: include-properties
        in: query
        description: 'Includes content properties associated with this whiteboard in the response.

          The number of results will be limited to 50 and sorted in the default sort order.

          A `meta` and `_links` property will be present to indicate if more results are available and a link to retrieve the rest of the results.'
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Returned if the requested whiteboard is returned.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/WhiteboardSingle'
                - type: object
                  properties:
                    _links:
                      type: object
                      properties:
                        base:
                          type: string
                          description: Base url of the Confluence site.
        '400':
          description: Returned if an invalid request is provided.
          content: {}
        '401':
          description: 'Returned if the authentication credentials are incorrect or missing

            from the request.'
          content: {}
        '404':
          description: 'Returned if the calling user does not have permission to view the

            requested whiteboard or the whiteboard was not found.'
          content: {}
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - read:whiteboard:confluence
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - read:whiteboard:confluence
      x-atlassian-connect-scope: READ
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: false
    delete:
      tags:
      - Whiteboard
      operationId: deleteWhiteboard
      summary: Delete whiteboard
      description: 'Delete a whiteboard by id.


        Deleting a whiteboard moves the whiteboard to the trash, where it can be restored later


        **Permissions required**:

        Permission to view the whiteboard and its corresponding space.

        Permission to delete whiteboards in the space.'
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the whiteboard to be deleted.
        schema:
          format: int64
          type: integer
      responses:
        '204':
          description: Returned if the whiteboard was successfully deleted.
          content: {}
        '400':
          description: Returned if an invalid request is provided.
          content: {}
        '401':
          description: 'Returned if the authentication credentials are incorrect or missing

            from the request.'
          content: {}
        '404':
          description: 'Returned if:

            - The provided whiteboard does not exist

            - The user does not have permissions to view the whiteboard

            - The user does not have the needed permissions to delete a whiteboard in the space'
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - delete:whiteboard:confluence
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - delete:whiteboard:confluence
      x-atlassian-connect-scope: DELETE
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: false
components:
  schemas:
    WhiteboardSingle:
      type: object
      properties:
        id:
          type: string
          description: ID of the whiteboard.
        type:
          type: string
          description: The content type of the object.
        status:
          $ref: '#/components/schemas/ContentStatus'
        title:
          type: string
          description: Title of the whiteboard.
        parentId:
          type: string
          description: ID of the parent content, or null if there is no parent content.
        parentType:
          $ref: '#/components/schemas/ParentContentType'
        position:
          format: int32
          type:
          - integer
          - 'null'
          description: Position of the whiteboard within the given parent page tree.
        authorId:
          type: string
          description: The account ID of the user who created this whiteboard originally.
        ownerId:
          type: string
          description: The account ID of the user who owns this whiteboard.
        createdAt:
          type: string
          format: date-time
          description: Date and time when the whiteboard was created. In format "YYYY-MM-DDTHH:mm:ss.sssZ".
        spaceId:
          type: string
          description: ID of the space the whiteboard is in.
        version:
          $ref: '#/components/schemas/Version'
        _links:
          $ref: '#/components/schemas/WhiteboardLinks'
    WhiteboardLinks:
      type: object
      properties:
        webui:
          type: string
          description: Web UI link of the content.
        editui:
          type: string
          description: Edit UI link of the content.
    ContentStatus:
      enum:
      - current
      - draft
      - archived
      - historical
      - trashed
      - deleted
      - any
      type: string
      description: The status of the content.
    ParentContentType:
      type: string
      enum:
      - page
      - whiteboard
      - database
      - embed
      - folder
      description: Content type of the parent, or null if there is no parent.
    Version:
      type: object
      properties:
        createdAt:
          type: string
          format: date-time
          description: Date and time when the version was created. In format "YYYY-MM-DDTHH:mm:ss.sssZ".
        message:
          type: string
          description: Message associated with the current version.
        number:
          format: int32
          type: integer
          description: The version number.
        minorEdit:
          type: boolean
          description: Describes if this version is a minor version. Email notifications and activity stream updates are not created for minor versions.
        authorId:
          type: string
          description: The account ID of the user who created this version.
  requestBodies:
    WhiteboardCreateRequest:
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
            - spaceId
            properties:
              spaceId:
                type: string
                description: ID of the space.
              title:
                type: string
                description: Title of the whiteboard.
              parentId:
                type: string
                description: The parent content ID of the whiteboard.
              templateKey:
                type: string
                description: Providing a template key will add that template to the new whiteboard.
                enum:
                - 2x2-prioritization
                - 4ls-retro
                - annual-calendar
                - brainwriting
                - concept-map
                - crazy-8s
                - daily-sync
                - disruptive-brainstorm
                - dot-voting
                - elevator-pitch
                - flow-chart
                - gap-analysis
                - ice-breakers
                - incident-postmortem
                - journey-mapping-kit
                - kanban-board
                - lean-coffee
                - network-of-teams
                - org-chart
                - pi-planning
                - prioritization
                - prioritization-experiment
                - product-roadmap
                - product-vision-board
                - rice
                - sailboat-retro
                - service-blueprint
                - simple-retrospective
                - sprint-planning
                - sticky-note-pack
                - swimlanes
                - team-formation-guide
                - timeline
                - timeline-workflow
                - user-story-map
                - workflow
                - vision-board
                - venn-diagram
                - storyboard
                - action-plan
                - root-cause-analysis
                - executive-summary
                - stakeholder-mapping
                - annual-calendar-2025-2026
                - health-monitor
                - okr-planning
                - swot-analysis
                - poker-planning
                - fishbone-diagram
                - risk-assessment
                - bounded-context
                - hopes-and-fears
                - swimlane-vertical
              locale:
                type: string
                description: If templateKey is provided, locale will decide which language the template will be created with. If locale is omitted, the user's locale will be used.
                enum:
                - de-DE
                - cs-CZ
                - ko-KR
                - fr-FR
                - it-IT
                - ja-JP
                - nl-NL
                - nb-NO
                - da-DK
                - sv-SE
                - fi-FI
                - ru-RU
                - pl-PL
                - tr-TR
                - hu-HU
                - en-GB
                - en-US
                - pt-BR
                - zh-CN
                - zh-TW
                - es-ES
  securitySchemes:
    basicAuth:
      type: http
      description: You can access this resource via basic auth.
      scheme: basic
    oAuthDefinitions:
      type: oauth2
      description: This API uses OAuth 2 with the authorizationCode grant flow.
      flows:
        authorizationCode:
          authorizationUrl: https://auth.atlassian.com/authorize
          tokenUrl: https://auth.atlassian.com/oauth/token
          scopes:
            read:page:confluence: View pages and blogposts and their properties.
            read:space:confluence: View spaces and their properties.
            read:attachment:confluence: View attachments and their properties.
            read:comment:confluence: View comments and their properties.
            read:custom-content:confluence: View custom content and their properties.
            read:task:confluence: View tasks.
            read:whiteboard:confluence: View whiteboards and their properties.
            read:database:confluence: View databases and their properties.
            read:embed:confluence: View Smart Links in the content tree and their properties.
            read:folder:confluence: View folders and their properties.
            read:hierarchical-content:confluence: View children and descendants in the content tree.
            write:space:confluence: Create and update spaces and their properties.
            write:page:confluence: Create and update pages and blog posts and their properties.
            write:comment:confluence: Create and update comments and their properties.
            write:custom-content:confluence: Create and update custom content and their properties.
            write:whiteboard:confluence: Create and update whiteboards and their properties.
            write:database:confluence: Create and update databases and their properties.
            write:embed:confluence: Create and update Smart Links in the content tree and their properties.
            write:folder:confluence: Create and update folders and their properties.
            write:app-data:confluence: Create, update and delete app properties.
            delete:custom-content:confluence: Delete custom content.
            delete:page:confluence: Delete pages and blog posts.
            delete:comment:confluence: Delete comments.
            delete:whiteboard:confluence: Delete whiteboards.
            delete:database:confluence: Delete databases.
            delete:embed:confluence: Delete Smart Links in the content tree.
            delete:folder:confluence: Delete folders.
externalDocs:
  description: The online and complete version of the Confluence Cloud REST API docs.
  url: https://developer.atlassian.com/cloud/confluence/rest/v2
x-atlassian-narrative:
  documents:
  - title: About
    anchor: about
    body: This is the reference for the Confluence Cloud REST API v2, with definitions and performance intended to be an improvement over v1. You can click on the meatball menu in the upper right to download the spec or Postman collection.
  - title: Authentication and authorization
    anchor: auth
    body: '**Authentication:** If you are building a Cloud app, authentication is implemented via JWT or Oauth 2.0, depending on what you''re building (see [Authentication for apps](https://developer.atlassian.com/cloud/confluence/authentication-for-apps/)). Otherwise, if you are authenticating directly against the REST API, the REST API supports basic auth (see [Basic auth for REST APIs](https://developer.atlassian.com/cloud/confluence/basic-auth-for-rest-apis/)).


      **Authorization:** If you are building a Cloud app, authorization can be implemented by [scopes](https://developer.atlassian.com/cloud/confluence/scopes/) or by [OAuth 2.0 user impersonation](https://developer.atlassian.com/cloud/confluence/oauth-2-jwt-bearer-tokens-for-apps). Otherwise, if you are making calls directly against the REST API, authorization is based on the user used in the authentication process.


      See [Security overview](https://developer.atlassian.com/cloud/confluence/security-overview/) for more details on authentication and authorization.'
  - title: Using the REST API
    anchor: using
    body: "**Pagination:** The Confluence REST API v2 uses cursor-based pagination: a method that returns a response with multiple objects can only return a limited number at one time. This limits the size of responses and conserves server resources.\n\nUse the 'limit' and 'cursor' parameters on endpoints that return multiple objects to work with pagination. First, make a request with your desired limit in the 'limit' parameter, then observe the `Link` header in the response. If there are additional entities to be retrieved, the `next` URL in the `Link` header will allow you to retrieve the next set of results. This relative URL will also be available under the `_links.next` property of paginated responses. \n\nFor example, the following request will return 5 page objects (if there are 5 present in the target site).\n```\nGET /wiki/api/v2/pages?limit=5\n```\n\nIf there are additional pages available, the `Link` header will look like:\n```\n</wiki/api/v2/pages?limit=5&cursor=<cursor token>>; rel=\"next\"\n```\nThe URL within the `Link` header will allow you to access the next 5 pages, while the `rel=\"next\"` denotes that the URL refers to the \"next\" set of pages. Relations for a single URL are separated by semicolons (;) and URLs are separated by commas (,)\nIf there are no related URLs, the `Link` header will not be present in the response and neither will the `next` property for `_links` in the response body."