openapi: 3.1.0
info:
  title: Confluence Cloud REST API v2 Attachment Page API
  description: Next generation REST API for Confluence Cloud providing access to pages, spaces, comments, blog posts, attachments, labels, and other content management operations. This API offers improved performance, consistent pagination, and new features compared to the v1 API.
  version: 2.0.0
  contact:
    name: Atlassian
    url: https://developer.atlassian.com/cloud/confluence/
    email: ecosystem@atlassian.com
  license:
    name: Atlassian Developer Terms
    url: https://developer.atlassian.com/platform/marketplace/atlassian-developer-terms/
  termsOfService: https://www.atlassian.com/legal/cloud-terms-of-service
  x-logo:
    url: https://www.atlassian.com/dam/jcr:5d1374c2-276f-4bca-9ce4-b3f5e2dd5d6c/confluence-icon-gradient-blue.svg
servers:
- url: https://{domain}.atlassian.net/wiki/api/v2
  description: Confluence Cloud
  variables:
    domain:
      default: your-domain
      description: Your Atlassian Cloud site domain
security:
- basicAuth: []
- oAuth2: []
- bearerAuth: []
tags:
- name: Page
  description: Create, retrieve, update, and delete pages
  externalDocs:
    url: https://developer.atlassian.com/cloud/confluence/rest/v2/api-group-page/
paths:
  /pages:
    get:
      operationId: getPages
      summary: Get Pages
      description: Returns all pages. The number of results is limited by the limit parameter and additional results can be retrieved via the next cursor. Results can be filtered by space, status, title, and body format.
      tags:
      - Page
      parameters:
      - $ref: '#/components/parameters/PageIdParam'
      - $ref: '#/components/parameters/SpaceIdFilter'
      - $ref: '#/components/parameters/StatusFilter'
      - $ref: '#/components/parameters/TitleFilter'
      - $ref: '#/components/parameters/BodyFormatParam'
      - $ref: '#/components/parameters/SortParam'
      - $ref: '#/components/parameters/CursorParam'
      - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Returned if the requested pages are returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageBulk'
              examples:
                Getpages200Example:
                  summary: Default getPages 200 response
                  x-microcks-default: true
                  value:
                    results:
                    - id: abc123
                      status: current
                      title: Example Title
                      spaceId: '500123'
                      parentId: '500123'
                      parentType: page
                      position: 10
                      authorId: '500123'
                      ownerId: '500123'
                      lastOwnerId: '500123'
                      createdAt: '2026-01-15T10:30:00Z'
                    _links:
                      next: example_value
                      base: example_value
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createPage
      summary: Create Page
      description: Creates a page in the space. Pages can be created as a child of another page by specifying the parentId. Pages are created in the current status (draft or current).
      tags:
      - Page
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PageCreateRequest'
            examples:
              CreatepageRequestExample:
                summary: Default createPage request
                x-microcks-default: true
                value:
                  spaceId: '500123'
                  status: current
                  title: Example Title
                  parentId: '500123'
                  body:
                    representation: storage
                    value: example_value
      responses:
        '200':
          description: Returned if the page was created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page'
              examples:
                Createpage200Example:
                  summary: Default createPage 200 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    status: current
                    title: Example Title
                    spaceId: '500123'
                    parentId: '500123'
                    parentType: page
                    position: 10
                    authorId: '500123'
                    ownerId: '500123'
                    lastOwnerId: '500123'
                    createdAt: '2026-01-15T10:30:00Z'
                    version:
                      createdAt: '2026-01-15T10:30:00Z'
                      message: example_value
                      number: 10
                      minorEdit: true
                      authorId: '500123'
                    body: {}
                    labels:
                      results:
                      - {}
                    properties:
                      results:
                      - {}
                    operations:
                      results:
                      - {}
                    likes:
                      results:
                      - {}
                    versions:
                      results:
                      - {}
                    _links:
                      webui: example_value
                      editui: example_value
                      tinyui: example_value
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /pages/{id}:
    get:
      operationId: getPageById
      summary: Get Page by Id
      description: Returns a specific page. The response includes the page body in the requested format, version information, and links.
      tags:
      - Page
      parameters:
      - $ref: '#/components/parameters/ContentIdPath'
      - $ref: '#/components/parameters/BodyFormatParam'
      - $ref: '#/components/parameters/GetDraftParam'
      - $ref: '#/components/parameters/VersionParam'
      responses:
        '200':
          description: Returned if the requested page is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page'
              examples:
                Getpagebyid200Example:
                  summary: Default getPageById 200 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    status: current
                    title: Example Title
                    spaceId: '500123'
                    parentId: '500123'
                    parentType: page
                    position: 10
                    authorId: '500123'
                    ownerId: '500123'
                    lastOwnerId: '500123'
                    createdAt: '2026-01-15T10:30:00Z'
                    version:
                      createdAt: '2026-01-15T10:30:00Z'
                      message: example_value
                      number: 10
                      minorEdit: true
                      authorId: '500123'
                    body: {}
                    labels:
                      results:
                      - {}
                    properties:
                      results:
                      - {}
                    operations:
                      results:
                      - {}
                    likes:
                      results:
                      - {}
                    versions:
                      results:
                      - {}
                    _links:
                      webui: example_value
                      editui: example_value
                      tinyui: example_value
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updatePage
      summary: Update Page
      description: Updates a page by id. The request body must include the current version number, the new title, the space id, the status, and the body in the specified representation.
      tags:
      - Page
      parameters:
      - $ref: '#/components/parameters/ContentIdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PageUpdateRequest'
            examples:
              UpdatepageRequestExample:
                summary: Default updatePage request
                x-microcks-default: true
                value:
                  id: abc123
                  status: current
                  title: Example Title
                  spaceId: '500123'
                  parentId: '500123'
                  body:
                    representation: storage
                    value: example_value
                  version:
                    number: 10
                    message: example_value
      responses:
        '200':
          description: Returned if the page was updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page'
              examples:
                Updatepage200Example:
                  summary: Default updatePage 200 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    status: current
                    title: Example Title
                    spaceId: '500123'
                    parentId: '500123'
                    parentType: page
                    position: 10
                    authorId: '500123'
                    ownerId: '500123'
                    lastOwnerId: '500123'
                    createdAt: '2026-01-15T10:30:00Z'
                    version:
                      createdAt: '2026-01-15T10:30:00Z'
                      message: example_value
                      number: 10
                      minorEdit: true
                      authorId: '500123'
                    body: {}
                    labels:
                      results:
                      - {}
                    properties:
                      results:
                      - {}
                    operations:
                      results:
                      - {}
                    likes:
                      results:
                      - {}
                    versions:
                      results:
                      - {}
                    _links:
                      webui: example_value
                      editui: example_value
                      tinyui: example_value
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deletePage
      summary: Delete Page
      description: Deletes a page by id. By default pages are moved to trash. To purge a page permanently, set the purge parameter to true.
      tags:
      - Page
      parameters:
      - $ref: '#/components/parameters/ContentIdPath'
      - name: purge
        in: query
        description: If true, the page is permanently deleted instead of moved to trash.
        schema:
          type: boolean
          default: false
        example: true
      responses:
        '204':
          description: Returned if the page was deleted successfully.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /pages/{id}/children:
    get:
      operationId: getChildPages
      summary: Get Child Pages
      description: Returns the child pages of a specific page, ordered by position in the page tree.
      tags:
      - Page
      parameters:
      - $ref: '#/components/parameters/ContentIdPath'
      - $ref: '#/components/parameters/CursorParam'
      - $ref: '#/components/parameters/LimitParam'
      - $ref: '#/components/parameters/SortParam'
      responses:
        '200':
          description: Returned if the child pages are returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageBulk'
              examples:
                Getchildpages200Example:
                  summary: Default getChildPages 200 response
                  x-microcks-default: true
                  value:
                    results:
                    - id: abc123
                      status: current
                      title: Example Title
                      spaceId: '500123'
                      parentId: '500123'
                      parentType: page
                      position: 10
                      authorId: '500123'
                      ownerId: '500123'
                      lastOwnerId: '500123'
                      createdAt: '2026-01-15T10:30:00Z'
                    _links:
                      next: example_value
                      base: example_value
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /spaces/{id}/pages:
    get:
      operationId: getPagesInSpace
      summary: Get Pages in Space
      description: Returns all pages in a specific space. Supports filtering by status and depth.
      tags:
      - Page
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the space.
        schema:
          type: integer
          format: int64
        example: abc123
      - name: depth
        in: query
        description: Filter by depth in the page tree. Use root to get only top-level pages.
        schema:
          type: string
          enum:
          - all
          - root
        example: all
      - $ref: '#/components/parameters/StatusFilter'
      - $ref: '#/components/parameters/BodyFormatParam'
      - $ref: '#/components/parameters/SortParam'
      - $ref: '#/components/parameters/CursorParam'
      - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Returned if the pages in the space are returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageBulk'
              examples:
                Getpagesinspace200Example:
                  summary: Default getPagesInSpace 200 response
                  x-microcks-default: true
                  value:
                    results:
                    - id: abc123
                      status: current
                      title: Example Title
                      spaceId: '500123'
                      parentId: '500123'
                      parentType: page
                      position: 10
                      authorId: '500123'
                      ownerId: '500123'
                      lastOwnerId: '500123'
                      createdAt: '2026-01-15T10:30:00Z'
                    _links:
                      next: example_value
                      base: example_value
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  parameters:
    GetDraftParam:
      name: get-draft
      in: query
      description: If true, returns the draft version of the page.
      schema:
        type: boolean
        default: false
    BodyFormatParam:
      name: body-format
      in: query
      description: The representation format for the content body.
      schema:
        type: string
        enum:
        - storage
        - atlas_doc_format
        - view
        - export_view
        - anonymous_export_view
        - editor
    SortParam:
      name: sort
      in: query
      description: Sort order for results. Prefix with - for descending order. Supported fields include id, title, created-date, and modified-date.
      schema:
        type: string
        enum:
        - id
        - -id
        - title
        - -title
        - created-date
        - -created-date
        - modified-date
        - -modified-date
    CursorParam:
      name: cursor
      in: query
      description: Used for pagination. The cursor value is returned in the response _links.next when there are more results.
      schema:
        type: string
    StatusFilter:
      name: status
      in: query
      description: Filter by content status.
      schema:
        type: string
        enum:
        - current
        - archived
        - draft
        - trashed
    ContentIdPath:
      name: id
      in: path
      required: true
      description: The ID of the content.
      schema:
        type: integer
        format: int64
    SpaceIdFilter:
      name: space-id
      in: query
      description: Filter by space ID. Multiple IDs can be specified.
      schema:
        type: array
        items:
          type: integer
          format: int64
    VersionParam:
      name: version
      in: query
      description: The version number of the content to retrieve.
      schema:
        type: integer
        format: int32
    TitleFilter:
      name: title
      in: query
      description: Filter by content title. Supports exact match.
      schema:
        type: string
    PageIdParam:
      name: id
      in: query
      description: Filter by page IDs. Multiple IDs can be specified as comma-separated values.
      schema:
        type: array
        items:
          type: integer
          format: int64
    LimitParam:
      name: limit
      in: query
      description: Maximum number of results to return.
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 250
        default: 25
  schemas:
    Version:
      type: object
      description: Version information for content.
      properties:
        createdAt:
          type: string
          format: date-time
          description: The ISO 8601 timestamp of this version.
          example: '2026-01-15T10:30:00Z'
        message:
          type: string
          description: The message associated with this version.
          example: example_value
        number:
          type: integer
          description: The version number.
          example: 10
        minorEdit:
          type: boolean
          description: Whether this was a minor edit.
          example: true
        authorId:
          type: string
          description: The Atlassian account ID of the version author.
          example: '500123'
    PaginationLinks:
      type: object
      description: Pagination links for cursor-based pagination.
      properties:
        next:
          type: string
          description: URL for the next page of results. Contains the cursor parameter.
          example: example_value
        base:
          type: string
          description: The base URL of the Confluence instance.
          example: example_value
    Error:
      type: object
      description: Error response from the Confluence API.
      properties:
        statusCode:
          type: integer
          description: The HTTP status code.
          example: 10
        data:
          type: object
          properties:
            authorized:
              type: boolean
            valid:
              type: boolean
            errors:
              type: array
              items:
                type: object
                properties:
                  message:
                    type: object
                    properties:
                      key:
                        type: string
                      args:
                        type: array
                        items:
                          type: string
                      translation:
                        type: string
            successful:
              type: boolean
          description: Details about the error.
          example: example_value
        message:
          type: string
          description: A human-readable error message.
          example: example_value
    PageLinks:
      type: object
      properties:
        webui:
          type: string
          description: Web UI link for the page.
          example: example_value
        editui:
          type: string
          description: Edit UI link for the page.
          example: example_value
        tinyui:
          type: string
          description: Shortened link for the page.
          example: example_value
    LikeArray:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Like'
          example: []
    PageUpdateRequest:
      type: object
      required:
      - id
      - status
      - title
      - body
      - version
      properties:
        id:
          type: string
          description: The ID of the page being updated.
          example: abc123
        status:
          type: string
          description: The status of the page.
          enum:
          - current
          - draft
          - archived
          example: current
        title:
          type: string
          description: The new title of the page.
          example: Example Title
        spaceId:
          type: string
          description: The ID of the space the page belongs to.
          example: '500123'
        parentId:
          type: string
          description: The ID of the new parent page.
          example: '500123'
        body:
          $ref: '#/components/schemas/BodyWrite'
        version:
          $ref: '#/components/schemas/VersionWrite'
    Operation:
      type: object
      properties:
        operation:
          type: string
          description: The operation type.
          enum:
          - create
          - read
          - update
          - delete
          - administer
          example: create
        targetType:
          type: string
          description: The target type for the operation.
          example: example_value
    Like:
      type: object
      properties:
        accountId:
          type: string
          description: The Atlassian account ID of the user who liked the content.
          example: '500123'
    Body:
      type: object
      description: The body content in various representations.
      properties:
        storage:
          $ref: '#/components/schemas/BodyRepresentation'
        atlas_doc_format:
          $ref: '#/components/schemas/BodyRepresentation'
        view:
          $ref: '#/components/schemas/BodyRepresentation'
    PageBulk:
      type: object
      description: A paginated list of pages.
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Page'
          example: []
        _links:
          $ref: '#/components/schemas/PaginationLinks'
    VersionArray:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Version'
          example: []
        _links:
          $ref: '#/components/schemas/PaginationLinks'
    OperationArray:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Operation'
          example: []
    ContentPropertyArray:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/ContentProperty'
          example: []
    Label:
      type: object
      description: Represents a label applied to Confluence content.
      properties:
        id:
          type: string
          description: The unique identifier of the label.
          example: abc123
        name:
          type: string
          description: The name of the label.
          example: Example Title
        prefix:
          type: string
          description: The prefix of the label (global, my, team).
          example: example_value
    ContentProperty:
      type: object
      properties:
        id:
          type: string
          example: abc123
        key:
          type: string
          example: example_value
        value:
          example: example_value
        version:
          $ref: '#/components/schemas/Version'
    VersionWrite:
      type: object
      required:
      - number
      properties:
        number:
          type: integer
          description: The new version number. Must be incremented by 1.
          example: 10
        message:
          type: string
          description: An optional message associated with this version.
          example: example_value
    BodyWrite:
      type: object
      required:
      - representation
      - value
      properties:
        representation:
          type: string
          description: The representation format of the body content.
          enum:
          - storage
          - atlas_doc_format
          - wiki
          - editor
          example: storage
        value:
          type: string
          description: The body content in the specified representation.
          example: example_value
    PageCreateRequest:
      type: object
      required:
      - spaceId
      - status
      - title
      - body
      properties:
        spaceId:
          type: string
          description: The ID of the space to create the page in.
          example: '500123'
        status:
          type: string
          description: The status of the page.
          enum:
          - current
          - draft
          example: current
        title:
          type: string
          description: The title of the page.
          example: Example Title
        parentId:
          type: string
          description: The ID of the parent page. If omitted, the page will be a root-level page.
          example: '500123'
        body:
          $ref: '#/components/schemas/BodyWrite'
    LabelArray:
      type: object
      description: A list of labels.
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Label'
          example: []
        _links:
          $ref: '#/components/schemas/PaginationLinks'
    Page:
      type: object
      description: Represents a Confluence page.
      properties:
        id:
          type: string
          description: The unique identifier of the page.
          example: abc123
        status:
          type: string
          description: The current status of the page.
          enum:
          - current
          - draft
          - archived
          - trashed
          example: current
        title:
          type: string
          description: The title of the page.
          example: Example Title
        spaceId:
          type: string
          description: The ID of the space this page belongs to.
          example: '500123'
        parentId:
          type: string
          description: The ID of the parent page, if the page is nested.
          example: '500123'
        parentType:
          type: string
          description: The type of the parent (page or space).
          enum:
          - page
          - space
          example: page
        position:
          type: integer
          description: The position of this page in the page tree relative to siblings.
          example: 10
        authorId:
          type: string
          description: The Atlassian account ID of the page author.
          example: '500123'
        ownerId:
          type: string
          description: The Atlassian account ID of the page owner.
          example: '500123'
        lastOwnerId:
          type: string
          description: The Atlassian account ID of the previous owner.
          example: '500123'
        createdAt:
          type: string
          format: date-time
          description: The ISO 8601 timestamp when the page was created.
          example: '2026-01-15T10:30:00Z'
        version:
          $ref: '#/components/schemas/Version'
        body:
          $ref: '#/components/schemas/Body'
        labels:
          $ref: '#/components/schemas/LabelArray'
        properties:
          $ref: '#/components/schemas/ContentPropertyArray'
        operations:
          $ref: '#/components/schemas/OperationArray'
        likes:
          $ref: '#/components/schemas/LikeArray'
        versions:
          $ref: '#/components/schemas/VersionArray'
        _links:
          $ref: '#/components/schemas/PageLinks'
    BodyRepresentation:
      type: object
      properties:
        representation:
          type: string
          description: The name of the representation format.
          example: example_value
        value:
          type: string
          description: The body content in this representation.
          example: example_value
  responses:
    Unauthorized:
      description: Returned if the authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: Returned if there is a version conflict during an update.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Returned if the requested resource is not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Returned if the request is malformed or contains invalid parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Basic authentication using email and API token. Provide your Atlassian account email as the username and an API token as the password.
    oAuth2:
      type: oauth2
      description: OAuth 2.0 (3LO) for Confluence Cloud apps.
      flows:
        authorizationCode:
          authorizationUrl: https://auth.atlassian.com/authorize
          tokenUrl: https://auth.atlassian.com/oauth/token
          scopes:
            read:confluence-content.all: Read Confluence content
            read:confluence-content.summary: Read Confluence content summaries
            write:confluence-content: Create and update Confluence content
            read:confluence-space.summary: Read Confluence space summaries
            write:confluence-space: Create and update Confluence spaces
            read:confluence-user: Read Confluence user information
            read:confluence-groups: Read Confluence groups
            write:confluence-file: Upload attachments to Confluence
            delete:confluence-content: Delete Confluence content
    bearerAuth:
      type: http
      scheme: bearer
      description: Personal Access Token or OAuth 2.0 Bearer token.
externalDocs:
  description: Confluence Cloud REST API v2 Documentation
  url: https://developer.atlassian.com/cloud/confluence/rest/v2/intro/