openapi: 3.2.0
info:
  title: Confluence Cloud REST API v2 Custom Content 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: Custom Content
  description: ''
paths:
  /blogposts/{id}/custom-content:
    get:
      tags:
      - Custom Content
      operationId: getCustomContentByTypeInBlogPost
      summary: Get custom content by type in blog post
      description: 'Returns all custom content for a given type within a given blogpost. The number of results is limited by the `limit` parameter and additional results (if available)

        will be available through the `next` URL present in the `Link` response header.


        **Permissions required**:

        Permission to view the custom content, the container of the custom content (blog post), and the corresponding space.'
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the blog post for which custom content should be returned.
        schema:
          format: int64
          type: integer
      - name: type
        in: query
        required: true
        description: 'The type of custom content being requested. See: https://developer.atlassian.com/cloud/confluence/custom-content/ for additional details on custom content.'
        schema:
          type: string
      - name: sort
        in: query
        required: false
        description: Used to sort the result by a particular field.
        schema:
          $ref: '#/components/schemas/CustomContentSortOrder'
      - name: cursor
        in: query
        required: false
        description: Used for pagination, this opaque cursor will be returned in the `next` URL in the `Link` response header. Use the relative URL in the `Link` header to retrieve the `next` set of results.
        schema:
          type: string
      - name: limit
        in: query
        description: Maximum number of pages per result to return. If more results exist, use the `Link` header to retrieve a relative URL that will return the next set of results.
        schema:
          format: int32
          default: 25
          minimum: 1
          maximum: 250
          type: integer
      - name: body-format
        in: query
        description: 'The content format types to be returned in the `body` field of the response. If available, the representation will be available under a response field of the same name under the `body` field.


          Note: If the custom content body type is `storage`, the `storage` and `atlas_doc_format` body formats are able to be returned. If the custom content body type is `raw`, only the `raw` body format is able to be returned.'
        schema:
          $ref: '#/components/schemas/CustomContentBodyRepresentation'
      responses:
        '200':
          description: Returned if the requested custom content is returned.
          content:
            application/json:
              schema:
                title: MultiEntityResult<CustomContent>
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomContentBulk'
                  _links:
                    $ref: '#/components/schemas/MultiEntityLinks'
          headers:
            Link:
              schema:
                type: string
              description: 'This header contains URL(s) within angle brackets and a relation description for each URL, describing how the provided URL relates to the incoming request''s URL. For example, rel="next" would be the URL necessary to get the next page of information. Example response header format: `Link: </wiki/api/v2/blogposts/{id}/custom-content?cursor=<opaque cursor token>>; rel="next", <https://site.atlassian.net/wiki>; rel="base"`

                '
        '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 given blog post is not found. Returned if the type of custom content is not found. Note, this is distinct from the type being present, but no instances of the type, which would be a 200 with empty results.
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - read:custom-content:confluence
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - read:custom-content:confluence
      x-atlassian-connect-scope: READ
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: false
  /custom-content:
    get:
      tags:
      - Custom Content
      operationId: getCustomContentByType
      summary: Get custom content by type
      description: 'Returns all custom content for a given type. The number of results is limited by the `limit` parameter and additional results (if available)

        will be available through the `next` URL present in the `Link` response header.


        **Permissions required**:

        Permission to view the custom content, the container of the custom content, and the corresponding space (if different from the container).'
      parameters:
      - name: type
        in: query
        required: true
        description: 'The type of custom content being requested. See: https://developer.atlassian.com/cloud/confluence/custom-content/ for additional details on custom content.'
        schema:
          type: string
      - name: id
        in: query
        required: false
        description: Filter the results based on custom content ids. Multiple custom content ids can be specified as a comma-separated list.
        schema:
          type: array
          maxItems: 250
          items:
            type: integer
            format: int64
      - name: space-id
        in: query
        required: false
        description: Filter the results based on space ids. Multiple space ids can be specified as a comma-separated list.
        schema:
          type: array
          maxItems: 100
          items:
            type: integer
            format: int64
      - name: sort
        in: query
        required: false
        description: Used to sort the result by a particular field.
        schema:
          $ref: '#/components/schemas/CustomContentSortOrder'
      - name: cursor
        in: query
        required: false
        description: Used for pagination, this opaque cursor will be returned in the `next` URL in the `Link` response header. Use the relative URL in the `Link` header to retrieve the `next` set of results.
        schema:
          type: string
      - name: limit
        in: query
        description: Maximum number of pages per result to return. If more results exist, use the `Link` header to retrieve a relative URL that will return the next set of results.
        schema:
          format: int32
          default: 25
          minimum: 1
          maximum: 250
          type: integer
      - name: body-format
        in: query
        description: 'The content format types to be returned in the `body` field of the response. If available, the representation will be available under a response field of the same name under the `body` field.


          Note: If the custom content body type is `storage`, the `storage` and `atlas_doc_format` body formats are able to be returned. If the custom content body type is `raw`, only the `raw` body format is able to be returned.'
        schema:
          $ref: '#/components/schemas/CustomContentBodyRepresentation'
      responses:
        '200':
          description: Returned if the requested custom content is returned.
          content:
            application/json:
              schema:
                title: MultiEntityResult<CustomContent>
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomContentBulk'
                  _links:
                    $ref: '#/components/schemas/MultiEntityLinks'
          headers:
            Link:
              schema:
                type: string
              description: 'This header contains URL(s) within angle brackets and a relation description for each URL, describing how the provided URL relates to the incoming request''s URL. For example, rel="next" would be the URL necessary to get the next page of information. Example response header format: `Link: </wiki/api/v2/custom-content?cursor=<opaque cursor token>>; rel="next", <https://site.atlassian.net/wiki>; rel="base"`

                '
        '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 type of custom content is not found. Note, this is distinct from the type being present, but no instances of the type, which would be a 200 with empty results.
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - read:custom-content:confluence
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - read:custom-content:confluence
      x-atlassian-connect-scope: READ
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: false
    post:
      tags:
      - Custom Content
      operationId: createCustomContent
      summary: Create custom content
      description: 'Creates a new custom content in the given space, page, blogpost or other custom content.


        Only one of `spaceId`, `pageId`, `blogPostId`, or `customContentId` is required in the request body.

        **Permissions required**:

        Permission to view the content of the page or blogpost and its corresponding space. Permission to create custom content in the space.'
      requestBody:
        $ref: '#/components/requestBodies/CustomContentCreateRequest'
      responses:
        '201':
          description: Returned if the requested custom content is created successfully.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/CustomContentSingle'
                - type: object
                  properties:
                    _links:
                      type: object
                      properties:
                        base:
                          type: string
                          description: Base url of the Confluence site.
          headers:
            location:
              schema:
                type: string
              description: 'Relative link to created custom content Example response header format: `location: </wiki/api/v2/custom-content/<id>>`

                '
        '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 type of custom content is not found.
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - write:custom-content:confluence
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - write:custom-content:confluence
      x-atlassian-connect-scope: WRITE
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: false
  /custom-content/{id}:
    get:
      tags:
      - Custom Content
      operationId: getCustomContentById
      summary: Get custom content by id
      description: 'Returns a specific piece of custom content.


        **Permissions required**:

        Permission to view the custom content, the container of the custom content, and the corresponding space (if different from the container).'
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the custom content to be returned. If you don't know the custom content ID, use Get Custom Content by Type and filter the results.
        schema:
          format: int64
          type: integer
      - name: body-format
        in: query
        description: 'The content format types to be returned in the `body` field of the response. If available, the representation will be available under a response field of the same name under the `body` field.


          Note: If the custom content body type is `storage`, the `storage` and `atlas_doc_format` body formats are able to be returned. If the custom content body type is `raw`, only the `raw` body format is able to be returned.'
        schema:
          $ref: '#/components/schemas/CustomContentBodyRepresentationSingle'
      - name: version
        in: query
        description: Allows you to retrieve a previously published version. Specify the previous version's number to retrieve its details.
        schema:
          type: integer
      - name: include-labels
        in: query
        description: "Includes labels associated with this custom content in the response.\nThe number of results will be limited to 50 and sorted in the default sort order. \nA `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 custom content in the response.\nThe number of results will be limited to 50 and sorted in the default sort order. \nA `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-operations
        in: query
        description: "Includes operations associated with this custom content in the response, as defined in the `Operation` object.\nThe number of results will be limited to 50 and sorted in the default sort order. \nA `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-versions
        in: query
        description: "Includes versions associated with this custom content in the response.\nThe number of results will be limited to 50 and sorted in the default sort order. \nA `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-version
        in: query
        description: 'Includes the current version associated with this custom content in the response.

          By default this is included and can be omitted by setting the value to `false`.'
        schema:
          type: boolean
          default: true
      - name: include-collaborators
        in: query
        description: Includes collaborators on the custom content.
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Returned if the requested custom content is returned.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/CustomContentSingle'
                - 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 custom content or the custom content was not found.'
          content: {}
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - read:custom-content:confluence
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - read:custom-content:confluence
      x-atlassian-connect-scope: READ
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: false
    put:
      tags:
      - Custom Content
      operationId: updateCustomContent
      summary: Update custom content
      description: 'Update a custom content by id.

        At most one of `spaceId`, `pageId`, `blogPostId`, or `customContentId` is allowed in the request body.

        Note that if `spaceId` is specified, it must be the same as the `spaceId` used for creating the custom content

        as moving custom content to a different space is not supported.


        **Permissions required**:

        Permission to view the content of the page or blogpost and its corresponding space. Permission to update custom content in the space.'
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the custom content to be updated. If you don't know the custom content ID, use Get Custom Content by Type and filter the results.
        schema:
          format: int64
          type: integer
      requestBody:
        $ref: '#/components/requestBodies/CustomContentUpdateRequest'
      responses:
        '200':
          description: Returned if the requested custom content is updated successfully.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/CustomContentSingle'
                - type: object
                  properties:
                    _links:
                      type: object
                      properties:
                        base:
                          type: string
                          description: Base url of the Confluence site.
          headers:
            location:
              schema:
                type: string
              description: 'Relative link to updated custom content Example response header format: `location: </wiki/api/v2/custom-content/<id>>`

                '
        '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 type of custom content is not found.
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - write:custom-content:confluence
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - write:custom-content:confluence
      x-atlassian-connect-scope: WRITE
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: false
    delete:
      tags:
      - Custom Content
      operationId: deleteCustomContent
      summary: Delete custom content
      description: 'Delete a custom content by id.


        Deleting a custom content will either move it to the trash or permanently delete it (purge it), depending on the apiSupport.

        To permanently delete a **trashed** custom content, the endpoint must be called with the following param `purge=true`.


        **Permissions required**:

        Permission to view the content of the page or blogpost and its corresponding space.

        Permission to delete custom content in the space.

        Permission to administer the space (if attempting to purge).'
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the custom content to be deleted.
        schema:
          format: int64
          type: integer
      - name: purge
        in: query
        required: false
        description: If attempting to purge the custom content.
        schema:
          type: boolean
          default: false
      responses:
        '204':
          description: Returned if the custom content was 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 custom content is not found.
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - delete:custom-content:confluence
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - delete:custom-content:confluence
      x-atlassian-connect-scope: DELETE
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: false
  /pages/{id}/custom-content:
    get:
      tags:
      - Custom Content
      operationId: getCustomContentByTypeInPage
      summary: Get custom content by type in page
      description: 'Returns all custom content for a given type within a given page. The number of results is limited by the `limit` parameter and additional results (if available)

        will be available through the `next` URL present in the `Link` response header.


        **Permissions required**:

        Permission to view the custom content, the container of the custom content (page), and the corresponding space.'
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the page for which custom content should be returned.
        schema:
          format: int64
          type: integer
      - name: type
        in: query
        required: true
        description: 'The type of custom content being requested. See: https://developer.atlassian.com/cloud/confluence/custom-content/ for additional details on custom content.'
        schema:
          type: string
      - name: sort
        in: query
        required: false
        description: Used to sort the result by a particular field.
        schema:
          $ref: '#/components/schemas/CustomContentSortOrder'
      - name: cursor
        in: query
        required: false
        description: Used for pagination, this opaque cursor will be returned in the `next` URL in the `Link` response header. Use the relative URL in the `Link` header to retrieve the `next` set of results.
        schema:
          type: string
      - name: limit
        in: query
        description: Maximum number of pages per result to return. If more results exist, use the `Link` header to retrieve a relative URL that will return the next set of results.
        schema:
          format: int32
          default: 25
          minimum: 1
          maximum: 250
          type: integer
      - name: body-format
        in: query
        description: 'The content format types to be returned in the `body` field of the response. If available, the representation will be available under a response field of the same name under the `body` field.


          Note: If the custom content body type is `storage`, the `storage` and `atlas_doc_format` body formats are able to be returned. If the custom content body type is `raw`, only the `raw` body format is able to be returned.'
        schema:
          $ref: '#/components/schemas/CustomContentBodyRepresentation'
      responses:
        '200':
          description: Returned if the requested custom content is returned.
          content:
            application/json:
              schema:
                title: MultiEntityResult<CustomContent>
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomContentBulk'
                  _links:
                    $ref: '#/components/schemas/MultiEntityLinks'
          headers:
            Link:
              schema:
                type: string
              description: 'This header contains URL(s) within angle brackets and a relation description for each URL, describing how the provided URL relates to the incoming request''s URL. For example, rel="next" would be the URL necessary to get the next page of information. Example response header format: `Link: </wiki/api/v2/pages/{id}/custom-content?cursor=<opaque cursor token>>; rel="next", <https://site.atlassian.net/wiki>; rel="base"`

                '
        '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 given page is not found. Returned if the type of custom content is not found. Note, this is distinct from the type being present, but no instances of the type, which would be a 200 with empty results.
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - read:custom-content:confluence
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - read:custom-content:confluence
      x-atlassian-connect-scope: READ
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: false
  /spaces/{id}/custom-content:
    get:
      tags:
      - Custom Content
      operationId: getCustomContentByTypeInSpace
      summary: Get custom content by type in space
      description: 'Returns all custom content for a given type within a given space. The number of results is limited by the `limit` parameter and additional results (if available)

        will be available through the `next` URL present in the `Link` response header.


        **Permissions required**:

        Permission to view the custom content and the corresponding space.'
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the space for which custom content should be returned.
        schema:
          format: int64
          type: integer
      - name: type
        in: query
        required: true
        description: 'The type of custom content being requested. See: https://developer.atlassian.com/cloud/confluence/custom-content/ for additional details on custom content.'
        schema:
          type: string
      - name: cursor
        in: query
        required: false
        description: Used for pagination, this opaque cursor will be returned in the `next` URL in the `Link` response header. Use the relative URL in the `Link` header to retrieve the `next` set of results.
        schema:
          type: string
      - name: limit
        in: query
        description: Maximum number of pages per result to return. If more results exist, use the `Link` header to retrieve a relative URL that will return the next set of results.
        schema:
          format: int32
          default: 25
          minimum: 1
          maximum: 250
          type: integer
      - name: body-format
        in: query
        description: 'The content format types to be returned in the `body` field of the response. If available, the representation will be available under a response field of the same name under the `body` field.


          Note: If the custom content body type is `storage`, the `storage` and `atlas_doc_format` body formats are able to be returned. If the custom content body type is `raw`, only the `raw` body format is able to be returned.'
        schema:
          $ref: '#/components/schemas/CustomContentBodyRepresentation'
      responses:
        '200':
          description: Returned if the requested custom content is returned.
          content:
            application/json:
              schema:
                title: MultiEntityResult<CustomContent>
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomContentBulk'
                  _links:
                    $ref: '#/components/schemas/MultiEntityLinks'
          headers:
            Link:
              schema:
                type: string
              description: 'This header contains URL(s) within angle brackets and a relation description for each URL, describing how the provided URL relates to the incoming request''s URL. For example, rel="next" would be the URL necessary to get the next page of information. Example response header format: `Link: </wiki/api/v2/spaces/{id}/custom-content?cursor=<opaque cursor token>>; rel="next", <https://site.atlassian.net/wiki>; rel="base"`

                '
        '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 is not found. Returned if the type of custom content is not found. Note, this is distinct from the type being present, but no instances of the type, which would be a 200 with empty results.
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - read:custom-content:confluence
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - read:custom-content:confluence
      x-atlassian-connect-scope: READ
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: false
components:
  schemas:
    CustomContentBodyRepresentationSingle:
      enum:
      - raw
      - storage
      - atlas_doc_format
      - view
      - export_view
      - anonymous_export_view
      type: string
      description: The formats a custom content body can be represented as. A subset of BodyRepresentation.
    CustomContentNestedBodyWrite:
      type: object
      description: 'Body of the custom content. Only one body format should be specified as the property

        for this object, e.g. `storage`.'
      properties:
        storage:
          $ref: '#/components/schemas/CustomContentBodyWrite'
        atlas_doc_format:
          $ref: '#/components/schemas/CustomContentBodyWrite'
        raw:
          $ref: '#/components/schemas/CustomContentBodyWrite'
    CustomContentSortOrder:
      enum:
      - id
      - -id
      - created-date
      - -created-date
      - modified-date
      - -modified-date
      - title
      - -title
      type: string
      description: The sort fields for custom content. The default sort direction is ascending. To sort in descending order, append a `-` character before the sort field. For example, `fieldName` or `-fieldName`.
    BodyType:
      type: object
      properties:
        representation:
          type: string
          description: Type of content representation used for the value field.
        value:
          type: string
          description: Body of the content, in the format found in the representation field.
    CustomContentBodyBulk:
      type: object
      description: Contains fields for each representation type requested.
      properties:
        raw:
          $ref: '#/components/schemas/BodyType'
        storage:
          $ref: '#/components/schemas/BodyType'
        atlas_doc_format:
          $ref: '#/components/schemas/BodyType'
    ContentStatus:
      enum:
      - current
      - draft
      - archived
      - historical
      - trashed
      - deleted
      - any
      type: string
      description: The status of the content.
    OptionalFieldLinks:
      type: object
      properties:
        self:
          type: string
          description: A relative URL that can be used to fetch results beyond what this include parameter retrieves.
    OptionalFieldMeta:
      type: object
      properties:
        hasMore:
          type: boolean
          description: Indicates if there are more available results that can be fetched.
        cursor:
          type: string
          description: A token that can be used in the query parameter of the endpoint returned in the `_links` property to retrieve the next set of results.
    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.
    CustomContentBulk:
      type: object
      properties:
        id:
          type: string
          description: ID of the custom content.
        type:
          type: string
          description: The type of custom content.
        status:
          $ref: '#/components/schemas/ContentStatus'
        title:
          type: string
          description: Title of the custom content.
        spaceId:
          type: string
          description: 'ID of the space the custom content is in.


            Note: This is always returned, regardless of if the custom content has a container that is a space.'
        pageId:
          type: string
          description: 'ID of the containing page.


            Note: This is only returned if the custom content has a container that is a page.'
        blogPostId:
          type: string
          description: 'ID of the containing blog post.


            Note: This is only returned if the custom content has a container that is a blog post.'
        customContentId:
          type: string
          description: 'ID of the containing custom content.


            Note: This is only returned if the custom content has a container that is custom content.'
        authorId:
          type: string
          description: The account ID of the user who created this custom content originally.
        createdAt:
          type: string
          format: date-time
          description: Date and time when the custom content was created. In format "YYYY-MM-DDTHH:mm:ss.sssZ".
        version:
          $ref: '#/components/schemas/Version'
        body:
          $ref: '#/components/schemas/CustomContentBodyBulk'
        _links:
          $ref: '#/components/schemas/CustomContentLinks'
    CustomContentSingle:
      type: object
      properties:
        id:
          type: string
          description: ID of the custom content.
        type:
          type: string
          description: The type of custom content.
        status:
          $ref: '#/components/schemas/ContentStatus'
        title:
          type: string
          description: Title of the custom content.
        spaceId:
          type: string
          description: 'ID of the space the custom content is in.


            Note: This is always returned, regardless of if the custom content has a container that is a space.'
        pageId:
          type: string
          description: 'ID of the containing page.


            Note: This is only returned if the custom content has a container that is a page.'
        blogPostId:
          type: string
          description: 'ID of the containing blog post.


            Note: This is only returned if the custom content has a container that is a blog post.'
        customContentId:
          type: string
          description: 'ID of the containing custom content.


            Note: This is only returned if the custom content has a container that is custom content.'
        authorId:
          type: string
          description: The account ID of the user who created this custom content originally.
        createdAt:
          type: string
          format: date-time
          description: Date and time when the custom content was created. In format "YYYY-MM-DDTHH:mm:ss.sssZ".
        version:
          $ref: '#/components/schemas/Version'
        labels:
          type: object
          properties:
            results:
              type: array
              items:
                $ref: '#/components/schemas/Label'
            meta:
              $ref: '#/components/schemas/OptionalFieldMeta'
            _links:
              $ref: '#/components/schemas/OptionalFieldLinks'
        properties:
          type: object
          properties:
            results:
              type: array
              items:
                $ref: '#/components/schemas/ContentProperty'
            meta:
              $ref: '#/components/schemas/OptionalFieldMeta'
            _links:
              $ref: '#/components/schemas/OptionalFieldLinks'
        operations:
          type: object
          properties:
            results:
              type: array
              items:
                $ref: '#/components/schemas/Operation'
            meta:
              $ref: '#/components/schemas/OptionalFieldMeta'
            _links:
              $ref: '#/components/schemas/OptionalFieldLinks'
        versions:
          type: object
          properties:
            results:
              type: array
              items:
                $ref: '#/components/schemas/Version'
            meta:
              $ref: '#/components/schemas/OptionalFieldMeta'
            _links:
              $ref: '#/components/schemas/OptionalFieldLinks'
        body:
          $ref: '#/components/schemas/CustomContentBodySingle'
        _links:
          $ref: '#/components/schemas/CustomContentLinks'
    ContentProperty:
      type: object
      properties:
        id:
          type: string
          description: ID of the property
        key:
          type: string
          description: Key of the property
        value:
          description: Value of the property. Must be a valid JSON value.
        version:
          $ref: '#/components/schemas/Version'
    CustomContentBodyRepresentation:
      enum:
      - raw
      - storage
      - atlas_doc_format
      type: string
      description: The formats a custom content body can be represented as. A subset of BodyRepresentation.
    MultiEntityLinks:
      type: object
      properties:
        next:
          type: string
          description: 'Used for pagination. Contains the relative URL for the next set of results, using a cursor query parameter.

            This property will not be present if there is no additional data available.'
        base:
          type: string
          description: Base url of the Confluence site.
    CustomContentBodyWrite:
      type: object
      properties:
        representation:
          enum:
          - storage
          - atlas_doc_format
          - raw
          type: string
          description: Type of content representation used for the value field.
        value:
          type: string
          description: Body of the custom content, in the format found in the representation field.
    CustomContentBodySingle:
      type: object
      description: Contains fields for each representation type requested.
      properties:
        raw:
          $ref: '#/components/schemas/BodyType'
        storage:
          $ref: '#/components/schemas/BodyType'
        atlas_doc_format:
          $ref: '#/components/schemas/BodyType'
        view:
          $ref: '#/components/schemas/BodyType'
    Operation:
      type: object
      properties:
        operation:
          description: The type of operation.
          type: string
        targetType:
          description: The type of entity the operation type targets.
          type: string
    Label:
      type: object
      properties:
        id:
          type: string
          description: ID of the label.
        name:
          type: string
          description: Name of the label.
        prefix:
          type: string
          description: Prefix of the label.
    CustomContentLinks:
      type: object
      properties:
        webui:
          type: string
          description: Web UI link of the content.
  requestBodies:
    CustomContentCreateRequest:
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
            - body
            - title
            - type
            properties:
              type:
                type: string
                description: Type of custom content.
              status:
                enum:
                - current
                - draft
                type: string
                description: The status of the custom content. Defaults to `current` when status not provided.
              spaceId:
                type: string
                description: ID of the containing space.
              pageId:
                type: string
                description: ID of the containing page.
              blogPostId:
                type: string
                description: ID of the containing Blog Post.
              customContentId:
                type: string
                description: ID of the containing custom content.
              title:
                type: string
                description: Title of the custom content.
              body:
                oneOf:
                - $ref: '#/components/schemas/CustomContentBodyWrite'
                - $ref: '#/components/schemas/CustomContentNestedBodyWrite'
    CustomContentUpdateRequest:
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
            - body
            - id
            - status
            - title
            - type
            - version
            properties:
              id:
                type: string
                description: Id of custom content.
              type:
                type: string
                description: Type of custom content.
              status:
                enum:
                - current
                type: string
                description: The status of the custom content.
              spaceId:
                type: string
                description: ID of the containing space (must be the same as the spaceId of the space the custom content was created in).
              pageId:
                type: string
                description: ID of the containing page.
              blogPostId:
                type: string
                description: ID of the containing Blog Post.
              customContentId:
                type: string
                description: ID of the containing custom content.
              title:
                type: string
                description: Title of the custom content.
              body:
                oneOf:
                - $ref: '#/components/schemas/CustomContentBodyWrite'
                - $ref: '#/components/schemas/CustomContentNestedBodyWrite'
              version:
                type: object
                properties:
                  number:
                    format: int32
                    type: integer
                    description: The version number, must be incremented by one.
                  message:
                    type: string
                    description: An optional message to be stored with the version.
  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."