Atlassian Content Properties API

openapi: 3.2.0
info:
  title: Atlassian The Confluence Cloud REST Content Properties API
  description: This document describes the REST API and resources provided by Confluence.
  termsOfService: https://atlassian.com/terms/
  version: 1.0.0
servers:
- url: //your-domain.atlassian.net
tags:
- name: Content Properties
paths:
  /wiki/rest/api/content/{id}/property:
    get:
      tags:
      - Content Properties
      summary: Atlassian Get Content Properties
      deprecated: true
      description: 'Returns the properties for a piece of content. For more information

        about content properties, see Confluence entity properties.


        **Permissions required**:

        ''View'' permission for the space, and permission to view the content if it is a page.'
      operationId: atlassianGetcontentproperties
      parameters:
      - name: id
        in: path
        description: The ID of the content to be queried for its properties.
        required: true
        schema:
          type: string
      - name: key
        in: query
        description: The key of the content property.
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: expand
        in: query
        description: 'A multi-value parameter indicating which properties of the content to

          expand. By default, the `version` object is expanded.


          - `content` returns the content that the property is stored against.

          - `version` returns information about the version of the property, such

          as the version number, when it was created, etc.'
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - content
            - version
      - name: start
        in: query
        description: The starting index of the returned properties.
        schema:
          minimum: 0
          type: integer
          format: int32
          default: 0
      - name: limit
        in: query
        description: 'The maximum number of properties to return per page.

          Note, this may be restricted by fixed system limits.'
        schema:
          minimum: 0
          type: integer
          format: int32
          default: 10
      responses:
        '200':
          description: Returned if the requested properties are returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentPropertyArray'
        '404':
          description: 'Returned if;


            - There is no content with the given ID

            - The calling user does not have permission to view the content.'
          content: {}
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - read:confluence-props
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - read:confluence-props
      - scheme: oAuthDefinitions
        state: Beta
        scopes:
        - read:content-details:confluence
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: false
      x-atlassian-connect-scope: READ
    post:
      tags:
      - Content Properties
      summary: Atlassian Create Content Property
      deprecated: true
      description: 'Creates a property for an existing piece of content. For more information

        about content properties, see Confluence entity properties.


        This is the same as Create content property for key

        except that the key is specified in the request body instead of as a

        path parameter.


        Content properties can also be added when creating a new piece of content

        by including them in the `metadata.properties` of the request.


        **Permissions required**:

        Permission to update the content.'
      operationId: atlassianCreatecontentproperty
      parameters:
      - name: id
        in: path
        description: The ID of the content to add the property to.
        required: true
        schema:
          type: string
      requestBody:
        description: The content property to be created.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContentPropertyCreate'
        required: true
      responses:
        '200':
          description: Returned if the content property is created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentProperty'
        '400':
          description: 'Returned if;


            - The content already has a property with the given key.

            - The key is too long.

            - The key is empty.'
          content: {}
        '403':
          description: 'Returned if the user does not have permission to edit the content

            with the given ID.'
          content: {}
        '413':
          description: Returned if the value is too long.
          content: {}
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - write:confluence-props
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - write:confluence-props
      - scheme: oAuthDefinitions
        state: Beta
        scopes:
        - read:content.property:confluence
        - write:content.property:confluence
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: false
      x-codegen-request-body-name: body
      x-atlassian-connect-scope: WRITE
  /wiki/rest/api/content/{id}/property/{key}:
    get:
      tags:
      - Content Properties
      summary: Atlassian Get Content Property
      deprecated: true
      description: 'Returns a content property for a piece of content. For more information, see

        Confluence entity properties.


        **Permissions required**:

        ''View'' permission for the space, and permission to view the content if it is a page.'
      operationId: atlassianGetcontentproperty
      parameters:
      - name: id
        in: path
        description: The ID of the content to be queried for the property.
        required: true
        schema:
          type: string
      - name: key
        in: path
        description: The key of the content property.
        required: true
        schema:
          type: string
      - name: expand
        in: query
        description: 'A multi-value parameter indicating which properties of the content to

          expand. By default, the `version` object is expanded.


          - `content` returns the content that the property is stored against.

          - `version` returns information about the version of the property, such

          as the version number, when it was created, etc.'
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - content
            - version
      - name: status
        in: query
        description: 'Filter the results to a set of content based on their status. If set to `any`,

          content with any status is returned. By default it will fetch current and archived statuses `?status=current&status=archived`.

          All supported statuses


          - any

          - archived

          - current

          - deleted

          - draft

          - trashed'
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
          default:
          - current
          - archived
          enum:
          - any
          - archived
          - current
          - deleted
          - draft
          - trashed
      responses:
        '200':
          description: Returned if the content property is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentProperty'
        '404':
          description: 'Returned if;


            - The calling user does not have permission to view the content.

            - There is no content with the given ID.

            - There is no property with the given key.'
          content: {}
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - read:confluence-props
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - read:confluence-props
      - scheme: oAuthDefinitions
        state: Beta
        scopes:
        - read:content-details:confluence
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: false
      x-atlassian-connect-scope: READ
    put:
      tags:
      - Content Properties
      summary: Atlassian Update Content Property
      deprecated: true
      description: 'Updates an existing content property. This method will also create a new

        property for a piece of content, if the property key does not exist and

        the property version is 1. For more information about content properties, see

        Confluence entity properties.


        **Permissions required**:

        Permission to update the content.'
      operationId: atlassianUpdatecontentproperty
      parameters:
      - name: id
        in: path
        description: The ID of the content that the property belongs to.
        required: true
        schema:
          type: string
      - name: key
        in: path
        description: The key of the property.
        required: true
        schema:
          type: string
      requestBody:
        description: The content property being updated.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContentPropertyUpdate'
        required: true
      responses:
        '200':
          description: Returned if the content property is created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentProperty'
        '400':
          description: 'Returned if;


            - The content already a property with the given key.

            - The key is too long.

            - The key is empty.'
          content: {}
        '403':
          description: 'Returned if the user does not have permission to edit the content

            with the given ID.'
          content: {}
        '404':
          description: 'Returned if;


            - There is no content with the given ID.

            - The calling user does not have permission to view the content.

            - There is no property with the given key and the version number is not 1.'
          content: {}
        '409':
          description: Returned if the property version is not correctly incremented.
          content: {}
        '413':
          description: Returned if the value is too long.
          content: {}
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - write:confluence-props
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - write:confluence-props
      - scheme: oAuthDefinitions
        state: Beta
        scopes:
        - read:content.property:confluence
        - write:content.property:confluence
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: false
      x-codegen-request-body-name: body
      x-atlassian-connect-scope: WRITE
    post:
      tags:
      - Content Properties
      summary: Atlassian Create Content Property For Key
      deprecated: true
      description: 'Creates a property for an existing piece of content. For more information

        about content properties, see Confluence entity properties.


        This is the same as Create content property

        except that the key is specified as a path parameter instead of in the

        request body.


        Content properties can also be added when creating a new piece of content

        by including them in the `metadata.properties` of the request.


        **Permissions required**:

        Permission to update the content.'
      operationId: atlassianCreatecontentpropertyforkey
      parameters:
      - name: id
        in: path
        description: The ID of the content to add the property to.
        required: true
        schema:
          type: string
      - name: key
        in: path
        description: The key of the content property. Required.
        required: true
        schema:
          type: string
      requestBody:
        description: The content property to be created.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContentPropertyCreateNoKey'
        required: true
      responses:
        '200':
          description: Returned if the content property is created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentProperty'
        '400':
          description: 'Returned if;


            - The content already has a property with the given key.

            - The key is too long.

            - The key is empty.'
          content: {}
        '403':
          description: 'Returned if the user does not have permission to edit the content

            with the given ID.'
          content: {}
        '413':
          description: Returned if the value is too long.
          content: {}
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - write:confluence-props
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - write:confluence-props
      - scheme: oAuthDefinitions
        state: Beta
        scopes:
        - read:content.property:confluence
        - write:content.property:confluence
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: false
      x-codegen-request-body-name: body
      x-atlassian-connect-scope: WRITE
    delete:
      tags:
      - Content Properties
      summary: Atlassian Delete Content Property
      deprecated: true
      description: 'Deletes a content property. For more information about content properties, see

        Confluence entity properties.


        **Permissions required**:

        Permission to update the content.'
      operationId: atlassianDeletecontentproperty
      parameters:
      - name: id
        in: path
        description: The ID of the content that the property belongs to.
        required: true
        schema:
          type: string
      - name: key
        in: path
        description: The key of the property.
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Returned if the content property is deleted.
          content: {}
        '403':
          description: 'Returned if the user does not have permission to delete content

            with the given ID.'
          content: {}
        '404':
          description: 'Returned if;


            - There is no content with the given ID.

            - The calling user does not have permission to view the content.'
          content: {}
      security:
      - basicAuth: []
      - oAuthDefinitions:
        - write:confluence-props
      x-atlassian-oauth2-scopes:
      - scheme: oAuthDefinitions
        state: Current
        scopes:
        - write:confluence-props
      - scheme: oAuthDefinitions
        state: Beta
        scopes:
        - write:content.property:confluence
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: false
      x-atlassian-connect-scope: WRITE
components:
  schemas:
    ContentPropertyCreate:
      required:
      - key
      - value
      type: object
      additionalProperties: true
      properties:
        key:
          maxLength: 255
          type: string
          description: The key of the new property.
        value:
          oneOf:
          - type: array
            items:
              type: string
          - type: boolean
          - type: object
            additionalProperties: true
            properties: {}
          - type: string
          description: The value of the content property. This can be empty or a complex object.
    ContentPropertyArray:
      required:
      - _links
      - limit
      - results
      - size
      - start
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/ContentProperty'
        start:
          type: integer
          format: int32
        limit:
          type: integer
          format: int32
        size:
          type: integer
          format: int32
        _links:
          $ref: '#/components/schemas/GenericLinks'
    ContentProperty:
      required:
      - _links
      - id
      - key
      - value
      type: object
      additionalProperties: true
      properties:
        id:
          type: string
        key:
          type: string
        value:
          oneOf:
          - type: array
            items:
              type: string
          - type: boolean
          - type: object
            additionalProperties: true
            properties: {}
          - type: string
          description: The value of the content property. This can be empty or a complex object.
        version:
          required:
          - message
          - minorEdit
          - number
          - when
          type: object
          additionalProperties: true
          properties:
            when:
              type: string
              format: date-time
            message:
              type: string
            number:
              type: integer
              format: int32
            minorEdit:
              type: boolean
            contentTypeModified:
              type: boolean
              description: True if content type is modifed in this version (e.g. page to blog)
        _links:
          $ref: '#/components/schemas/GenericLinks'
        _expandable:
          type: object
          properties:
            content:
              type: string
            additionalProperties:
              type: string
    GenericLinks:
      type: object
      additionalProperties:
        oneOf:
        - type: object
          additionalProperties: true
        - type: string
    ContentPropertyCreateNoKey:
      required:
      - value
      type: object
      additionalProperties: true
      properties:
        value:
          oneOf:
          - type: array
            items:
              type: string
          - type: boolean
          - type: object
            additionalProperties: true
            properties: {}
          - type: string
          description: The value of the content property. This can be empty or a complex object.
    ContentPropertyUpdate:
      required:
      - value
      - version
      type: object
      additionalProperties: true
      properties:
        value:
          oneOf:
          - type: array
            items:
              type: string
          - type: boolean
          - type: object
            additionalProperties: true
            properties: {}
          - type: string
          description: The value of the content property. This can be empty or a complex object.
        version:
          required:
          - number
          type:
          - object
          - 'null'
          additionalProperties: true
          properties:
            number:
              oneOf:
              - type: integer
              - type: string
              description: 'The new version for the updated content property. Set this to the

                current version number incremented by one. To get the current

                version number, use ''Get content property'' and retrieve

                `version.number`.'
              format: int32
            minorEdit:
              type: boolean
              description: 'If `minorEdit` is set to ''true'', no notification email or activity

                stream will be generated for the change.'
              default: true
          description: The version number of the property.
  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:confluence-content.all: Read all content, including content body (expansions permitted). Note, APIs using this scope may also return data allowed by read:confluence-space.summary. However, this scope is not a substitute for read:confluence-space.summary.
            read:confluence-content.permission: Read content permissions.
            read:confluence-content.summary: Read a summary of the content, which is the content without expansions. Note, APIs using this scope may also return data allowed by read:confluence-space.summary. However, this scope is not a substitute for read:confluence-space.summary.
            write:confluence-content: Permits the creation of pages, blogs, comments and questions.
            read:confluence-space.summary: Read a summary of space information without expansions.
            write:confluence-space: Create, update and delete space information.
            write:confluence-file: Upload attachments.
            read:confluence-props: Read content properties.
            write:confluence-props: Write content properties.
            search:confluence: Search Confluence. Note, APIs using this scope may also return data allowed by read:confluence-space.summary and read:confluence-content.summary. However, this scope is not a substitute for read:confluence-space.summary or read:confluence-content.summary.
            manage:confluence-configuration: Manage global settings.
            read:confluence-groups: Read user groups.
            write:confluence-groups: Create, remove and update user groups.
            read:confluence-user: Read users.
            readonly:content.attachment:confluence: Download attachments of a Confluence page or blogpost that you have access to.
            read:content:confluence: View content.
            read:content-details:confluence: View content details.
            write:content:confluence: Create and update content.
            delete:content:confluence: Delete content.
            read:space-details:confluence: View space details.
            read:analytics.content:confluence: View analytics for content.
            read:audit-log:confluence: View audit records.
            write:audit-log:confluence: Create audit records.
            read:configuration:confluence: View Confluence settings.
            write:configuration:confluence: Update Confluence settings.
            read:page:confluence: View pages.
            write:page:confluence: Create and update pages.
            delete:page:confluence: Delete pages.
            read:blogpost:confluence: View blogposts.
            write:blogpost:confluence: Create and update blogposts.
            delete:blogpost:confluence: Delete blogposts.
            read:whiteboard:confluence: View whiteboards.
            write:whiteboard:confluence: Create and update whiteboards.
            delete:whiteboard:confluence: Delete whiteboards.
            read:custom-content:confluence: View custom content.
            write:custom-content:confluence: Create and update custom content.
            delete:custom-content:confluence: Delete custom content.
            read:attachment:confluence: View and download content attachments.
            write:attachment:confluence: Create and update attachments.
            delete:attachment:confluence: Delete attachments.
            read:comment:confluence: View comments.
            write:comment:confluence: Create and update comments.
            delete:comment:confluence: Delete comments.
            read:template:confluence: View content templates.
            write:template:confluence: Create, update and delete content templates.
            read:label:confluence: View labels.
            write:label:confluence: Add and remove labels.
            read:content.permission:confluence: Check content permissions.
            read:content.property:confluence: View content properties.
            write:content.property:confluence: Create, update and delete content properties.
            read:content.restriction:confluence: View content restrictions.
            write:content.restriction:confluence: Update content restrictions.
            read:content.metadata:confluence: View content summaries.
            read:watcher:confluence: View content watchers.
            write:watcher:confluence: Add and remove content watchers.
            read:group:confluence: View groups.
            write:group:confluence: Create and delete groups.
            read:inlinetask:confluence: View tasks.
            write:inlinetask:confluence: Update tasks.
            read:relation:confluence: View entity relationships.
            write:relation:confluence: Create and update entity relationships.
            read:space:confluence: View spaces.
            write:space:confluence: Create and update spaces.
            delete:space:confluence: Delete spaces.
            read:space.permission:confluence: View space permissions.
            write:space.permission:confluence: Update space permissions.
            read:space.property:confluence: View space properties.
            write:space.property:confluence: Create, update and delete space properties.
            read:user.property:confluence: View user properties.
            write:user.property:confluence: Create, update and delete user properties.
            read:space.setting:confluence: View space settings.
            write:space.setting:confluence: Update space settings.
            read:user:confluence: View user details.
externalDocs:
  description: The online and complete version of the Confluence Cloud REST API docs.
  url: https://developer.atlassian.com/cloud/confluence/rest/
x-atlassian-narrative:
  documents:
  - title: About
    anchor: about
    body: 'This is the reference for the Confluence Cloud REST API. This API is the primary way to get and

      modify data in Confluence Cloud, whether you are developing an app or any other integration.

      Use it to interact with Confluence entities, like pages and blog posts, spaces, users, groups,

      and more.'
  - 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 are building (see [Security overview](https://developer.atlassian.com/cloud/confluence/security-overview/)). 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: Status codes
    anchor: status-code
    body: "The Confluence REST API uses the [standard HTTP status codes](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html).\n\nResponses that return an error status code will also return a response body, similar to the following:\n```json\n{\n  \"statusCode\": 404,\n  \"data\": {\n    \"authorized\": false,\n    \"valid\": false,\n    \"errors\": [\n      {\n        \"message\": {\n          \"translation\": \"This is an example error message.\",\n          \"args\": []\n        }\n      }\n    ],\n    \"successful\": false\n  },\n  \"message\": \"This is an example error message.\"\n}\n```"
  - title: Using the REST API
    anchor: using
    body: '**Expansion:** The Confluence REST API uses resource expansion: some parts of a resource are not returned unless explicitly specified. This simplifies responses and minimizes network traffic.


      To expand part of a resource in a request, use the `expand` query parameter and specify the entities to be expanded. If you need to expand nested entities, use the `.` dot notation. For example, the following request will expand information about the requested content''s space and labels:

      ```

      GET /wiki/rest/api/content/{id}?expand=space,metadata.labels

      ```

      **Pagination:** The Confluence REST API uses 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.


      Use the ''limit'' and ''start'' query parameters to specify pagination:


      - `limit` is the number of objects to return per page. This may be restricted by system limits.

      - `start` is the index of the first item returned in the page of results. The base index is 0.


      For example, the following request will return ten content objects, starting from the fifth object.

      ```

      GET /wiki/rest/api/content?start=4&limit=10

      ```

      **Special headers:**


      - `X-Atlassian-Token: no-check` request header must be specified for methods

      that are protected from Cross Site Request Forgery (XSRF/CSRF) attacks. This is

      stated in the method description, if required. For more information, see this

      [KB article](https://confluence.atlassian.com/cloudkb/xsrf-check-failed-when-calling-cloud-apis-826874382.html).'
  - title: Capabilities
    anchor: capabilities
    body: '**Webhooks:** A webhook is a user-defined callback over HTTP. You can use Confluence webhooks to notify your app or web application when certain events occur in Confluence. For example, when a page is created or updated. To learn more, see [Webhooks](https://developer.atlassian.com/cloud/confluence/modules/webhook/).


      **Content properties:** Content properties are a key-value storage associated with a piece of Confluence content. If you are building an app, this is one form of persistence that you can use. You can use the Confluence REST API to get, update, and delete content properties. To learn more, see [Content properties in the REST API](https://developer.atlassian.com/cloud/confluence/content-properties/).


      **CQL:** The Confluence Query Language (CQL) allows you to perform complex searches for content using an SQL-like syntax in the `search` resource. To learn more, see [Advanced searching using CQL](https://developer.atlassian.com/cloud/confluence/advanced-searching-using-cql/).'