Atlassian Confluence Relation API
The Atlassian Confluence Relation API enables creating and managing relationships between different pieces of content within Confluence.
OpenAPI Specification
openapi: 3.0.1
info:
title: 'Atlassian wiki/rest/api/relation/'
description: Needs description.
termsOfService: https://atlassian.com/terms/
version: 1.0.0
externalDocs:
description: The online and complete version of the Confluence Cloud REST API docs.
url: https://developer.atlassian.com/cloud/confluence/rest/
servers:
- url: //your-domain.atlassian.net
tags:
- name: Relation
paths:
/wiki/rest/api/relation/{relationName}/from/{sourceType}/{sourceKey}/to/{targetType}:
get:
tags:
- Relation
summary: Atlassian Find Target Entities Related To A Source Entity
description: >-
Returns all target entities that have a particular relationship to
the<br>source entity. Note, relationships are one way.<br><br>For
example, the following method finds all content that the current
user<br>has an 'ignore' relationship with:<br>`GET
/wiki/rest/api/relation/ignore/from/user/current/to/content`<br>Note,
'ignore' is an example custom relationship
type.<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:<br>Permission to view both the target entity and source
entity.
operationId: atlassianFindtargetfromsource
parameters:
- name: relationName
in: path
description: >-
The name of the relationship. This method supports relationships
created via
[Create
relationship](#api-wiki-rest-api-relation-relationname-from-sourcetype-sourcekey-to-targettype-targetkey-put).
Note, this method does not support 'like' or 'favourite'
relationships.
required: true
schema:
type: string
- name: sourceType
in: path
description: The source entity type of the relationship.
required: true
schema:
type: string
enum:
- user
- content
- space
- name: sourceKey
in: path
description: >-
The identifier for the source entity:
- If `sourceType` is `user`, then specify either `current`
(logged-in user), the user key of the user, or
the account ID of the user. Note that the user key has been
deprecated in favor of the account ID for this parameter. See the
[migration
guide](https://developer.atlassian.com/cloud/confluence/deprecation-notice-user-privacy-api-migration-guide/)
for details.
- If `sourceType` is 'content', then specify the content ID.
- If `sourceType` is 'space', then specify the space key.
required: true
schema:
type: string
- name: targetType
in: path
description: The target entity type of the relationship.
required: true
schema:
type: string
enum:
- user
- content
- space
- name: sourceStatus
in: query
description: |-
The status of the source. This parameter is only used when the
`sourceType` is 'content'.
schema:
type: string
- name: targetStatus
in: query
description: |-
The status of the target. This parameter is only used when the
`targetType` is 'content'.
schema:
type: string
- name: sourceVersion
in: query
description: |-
The version of the source. This parameter is only used when the
`sourceType` is 'content' and the `sourceStatus` is 'historical'.
schema:
type: integer
format: int32
- name: targetVersion
in: query
description: |-
The version of the target. This parameter is only used when the
`targetType` is 'content' and the `targetStatus` is 'historical'.
schema:
type: integer
format: int32
- name: expand
in: query
description: |-
A multi-value parameter indicating which properties of the response
object to expand.
- `relationData` returns information about the relationship, such as
who created it and when it was created.
- `source` returns the source entity.
- `target` returns the target entity.
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- relationData
- source
- target
- name: start
in: query
description: The starting index of the returned relationships.
schema:
minimum: 0
type: integer
format: int32
default: 0
- name: limit
in: query
description: |-
The maximum number of relationships to return per page.
Note, this may be restricted by fixed system limits.
schema:
minimum: 0
type: integer
format: int32
default: 25
responses:
'200':
description: Returned if the requested relationships are returned.
content:
application/json:
schema:
$ref: '#/components/schemas/RelationArray'
'400':
description: Returned if the request is invalid.
content: {}
'403':
description: |-
Returned if the user does not have permission to view the
relationships.
content: {}
'404':
description: Returned if the target entity does not exist.
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- read:confluence-content.summary
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- read:confluence-content.summary
- scheme: oAuthDefinitions
state: Beta
scopes:
- read:relation:confluence
- read:content-details:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: READ
/wiki/rest/api/relation/{relationName}/from/{sourceType}/{sourceKey}/to/{targetType}/{targetKey}:
get:
tags:
- Relation
summary: Atlassian Find Relationship From Source To Target
description: >-
Find whether a particular type of relationship exists from a
source<br>entity to a target entity. Note, relationships are one
way.<br><br>For example, you can use this method to find whether the
current user has<br>selected a particular page as a favorite (i.e. 'save
for later'):<br>`GET
/wiki/rest/api/relation/favourite/from/user/current/to/content/123`<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:<br>Permission to view both the target entity and source
entity.
operationId: atlassianGetrelationship
parameters:
- name: relationName
in: path
description: >-
The name of the relationship. This method supports the 'favourite'
(i.e. 'save for later') relationship as well as any other
relationship
types created via [Create
relationship](#api-wiki-rest-api-relation-relationname-from-sourcetype-sourcekey-to-targettype-targetkey-put).
required: true
schema:
type: string
- name: sourceType
in: path
description: |-
The source entity type of the relationship. This must be 'user', if
the `relationName` is 'favourite'.
required: true
schema:
type: string
enum:
- user
- content
- space
- name: sourceKey
in: path
description: >-
- The identifier for the source entity:
- If `sourceType` is `user`, then specify either `current`
(logged-in user), the user key of the user, or
the account ID of the user. Note that the user key has been
deprecated in favor of the account ID for this parameter. See the
[migration
guide](https://developer.atlassian.com/cloud/confluence/deprecation-notice-user-privacy-api-migration-guide/)
for details.
- If `sourceType` is 'content', then specify the content ID.
- If `sourceType` is 'space', then specify the space key.
required: true
schema:
type: string
- name: targetType
in: path
description: |-
The target entity type of the relationship. This must be 'space' or
'content', if the `relationName` is 'favourite'.
required: true
schema:
type: string
enum:
- user
- content
- space
- name: targetKey
in: path
description: >-
The identifier for the target entity:
- If `targetType` is `user`, then specify either `current`
(logged-in user), the user key of the user, or
the account ID of the user. Note that the user key has been
deprecated in favor of the account ID for this parameter. See the
[migration
guide](https://developer.atlassian.com/cloud/confluence/deprecation-notice-user-privacy-api-migration-guide/)
for details.
- If `targetType` is 'content', then specify the content ID.
- If `targetType` is 'space', then specify the space key.
required: true
schema:
type: string
- name: sourceStatus
in: query
description: |-
The status of the source. This parameter is only used when the
`sourceType` is 'content'.
schema:
type: string
- name: targetStatus
in: query
description: |-
The status of the target. This parameter is only used when the
`targetType` is 'content'.
schema:
type: string
- name: sourceVersion
in: query
description: |-
The version of the source. This parameter is only used when the
`sourceType` is 'content' and the `sourceStatus` is 'historical'.
schema:
type: integer
format: int32
- name: targetVersion
in: query
description: |-
The version of the target. This parameter is only used when the
`targetType` is 'content' and the `targetStatus` is 'historical'.
schema:
type: integer
format: int32
- name: expand
in: query
description: |-
A multi-value parameter indicating which properties of the response
object to expand.
- `relationData` returns information about the relationship, such as
who created it and when it was created.
- `source` returns the source entity.
- `target` returns the target entity.
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- relationData
- source
- target
responses:
'200':
description: Returned if the relationship exists.
content:
application/json:
schema:
$ref: '#/components/schemas/Relation'
'400':
description: Returned if the request is invalid.
content: {}
'401':
description: |-
Returned if the authentication credentials are incorrect or missing
from the request.
content: {}
'403':
description: |-
Returned if the user does not have permission to view the
relationship.
content: {}
'404':
description: Returned if the relationship does not exist.
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- read:confluence-content.summary
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- read:confluence-content.summary
- scheme: oAuthDefinitions
state: Beta
scopes:
- read:relation:confluence
- read:content-details:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: READ
put:
tags:
- Relation
summary: Atlassian Create Relationship
description: >-
Creates a relationship between two entities (user, space, content).
The<br>'favourite' relationship is supported by default, but you can use
this method<br>to create any type of relationship between two
entities.<br><br>For example, the following method creates a 'sibling'
relationship between<br>two pieces of content:<br>`GET
/wiki/rest/api/relation/sibling/from/content/123/to/content/456`<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:<br>Permission to access the Confluence site ('Can use'
global permission).
operationId: atlassianCreaterelationship
parameters:
- name: relationName
in: path
description: |-
The name of the relationship. This method supports the 'favourite'
(i.e. 'save for later') relationship. You can also specify any other
value for this parameter to create a custom relationship type.
required: true
schema:
type: string
- name: sourceType
in: path
description: |-
The source entity type of the relationship. This must be 'user', if
the `relationName` is 'favourite'.
required: true
schema:
type: string
enum:
- user
- content
- space
- name: sourceKey
in: path
description: >-
- The identifier for the source entity:
- If `sourceType` is 'user', then specify either 'current'
(logged-in
user) or the user key.
- If `sourceType` is 'content', then specify the content ID.
- If `sourceType` is 'space', then specify the space key.
required: true
schema:
type: string
- name: targetType
in: path
description: |-
The target entity type of the relationship. This must be 'space' or
'content', if the `relationName` is 'favourite'.
required: true
schema:
type: string
enum:
- user
- content
- space
- name: targetKey
in: path
description: >-
- The identifier for the target entity:
- If `sourceType` is 'user', then specify either 'current'
(logged-in
user) or the user key.
- If `sourceType` is 'content', then specify the content ID.
- If `sourceType` is 'space', then specify the space key.
required: true
schema:
type: string
- name: sourceStatus
in: query
description: |-
The status of the source. This parameter is only used when the
`sourceType` is 'content'.
schema:
type: string
- name: targetStatus
in: query
description: |-
The status of the target. This parameter is only used when the
`targetType` is 'content'.
schema:
type: string
- name: sourceVersion
in: query
description: |-
The version of the source. This parameter is only used when the
`sourceType` is 'content' and the `sourceStatus` is 'historical'.
schema:
type: integer
format: int32
- name: targetVersion
in: query
description: |-
The version of the target. This parameter is only used when the
`targetType` is 'content' and the `targetStatus` is 'historical'.
schema:
type: integer
format: int32
responses:
'200':
description: Returned if the relationship is created.
content:
application/json:
schema:
$ref: '#/components/schemas/Relation'
'400':
description: Returned if the request is invalid.
content: {}
'401':
description: |-
Returned if the authentication credentials are incorrect or missing
from the request.
content: {}
'403':
description: Returned if the user does not have permission to use Confluence.
content: {}
'404':
description: Returned if the user, space or content could not be found.
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- write:confluence-content
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- write:confluence-content
- scheme: oAuthDefinitions
state: Beta
scopes:
- read:relation:confluence
- read:space:confluence
- read:user:confluence
- read:content:confluence
- write:relation:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: WRITE
delete:
tags:
- Relation
summary: Atlassian Delete Relationship
description: >-
Deletes a relationship between two entities (user, space,
content).<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:<br>Permission to access the Confluence site ('Can use'
global permission).<br>For favourite relationships, the current user can
only delete their own<br>favourite relationships. A space administrator
can delete favourite<br>relationships for any user.
operationId: atlassianDeleterelationship
parameters:
- name: relationName
in: path
description: The name of the relationship.
required: true
schema:
type: string
- name: sourceType
in: path
description: |-
The source entity type of the relationship. This must be 'user', if
the `relationName` is 'favourite'.
required: true
schema:
type: string
enum:
- user
- content
- space
- name: sourceKey
in: path
description: >-
- The identifier for the source entity:
- If `sourceType` is 'user', then specify either 'current'
(logged-in
user) or the user key.
- If `sourceType` is 'content', then specify the content ID.
- If `sourceType` is 'space', then specify the space key.
required: true
schema:
type: string
- name: targetType
in: path
description: |-
The target entity type of the relationship. This must be 'space' or
'content', if the `relationName` is 'favourite'.
required: true
schema:
type: string
enum:
- user
- content
- space
- name: targetKey
in: path
description: >-
- The identifier for the target entity:
- If `sourceType` is 'user', then specify either 'current'
(logged-in
user) or the user key.
- If `sourceType` is 'content', then specify the content ID.
- If `sourceType` is 'space', then specify the space key.
required: true
schema:
type: string
- name: sourceStatus
in: query
description: |-
The status of the source. This parameter is only used when the
`sourceType` is 'content'.
schema:
type: string
- name: targetStatus
in: query
description: |-
The status of the target. This parameter is only used when the
`targetType` is 'content'.
schema:
type: string
- name: sourceVersion
in: query
description: |-
The version of the source. This parameter is only used when the
`sourceType` is 'content' and the `sourceStatus` is 'historical'.
schema:
type: integer
format: int32
- name: targetVersion
in: query
description: |-
The version of the target. This parameter is only used when the
`targetType` is 'content' and the `targetStatus` is 'historical'.
schema:
type: integer
format: int32
responses:
'204':
description: |-
Returned if the relationship is deleted or the relationship didn't
exist.
content: {}
'400':
description: Returned if the request is invalid.
content: {}
'401':
description: |-
Returned if the authentication credentials are incorrect or missing
from the request.
content: {}
'403':
description: |-
Returned if the user does not have permission to delete the
relationship.
content: {}
'404':
description: Returned if the user, space or content could not be found.
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- write:confluence-content
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- write:confluence-content
- scheme: oAuthDefinitions
state: Beta
scopes:
- write:relation:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: WRITE
/wiki/rest/api/relation/{relationName}/to/{targetType}/{targetKey}/from/{sourceType}:
get:
tags:
- Relation
summary: Atlassian Find Source Entities Related To A Target Entity
description: >-
Returns all target entities that have a particular relationship to
the<br>source entity. Note, relationships are one way.<br><br>For
example, the following method finds all users that have a
'collaborator'<br>relationship to a piece of content with an ID of
'1234':<br>`GET
/wiki/rest/api/relation/collaborator/to/content/1234/from/user`<br>Note,
'collaborator' is an example custom relationship
type.<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:<br>Permission to view both the target entity and source
entity.
operationId: atlassianFindsourcesfortarget
parameters:
- name: relationName
in: path
description: >-
The name of the relationship. This method supports relationships
created via
[Create
relationship](#api-wiki-rest-api-relation-relationname-from-sourcetype-sourcekey-to-targettype-targetkey-put).
Note, this method does not support 'like' or 'favourite'
relationships.
required: true
schema:
type: string
- name: sourceType
in: path
description: The source entity type of the relationship.
required: true
schema:
type: string
enum:
- user
- content
- space
- name: targetType
in: path
description: The target entity type of the relationship.
required: true
schema:
type: string
enum:
- user
- content
- space
- name: targetKey
in: path
description: >-
The identifier for the target entity:
- If `targetType` is `user`, then specify either `current`
(logged-in user), the user key of the user, or
the account ID of the user. Note that the user key has been
deprecated in favor of the account ID for this parameter. See the
[migration
guide](https://developer.atlassian.com/cloud/confluence/deprecation-notice-user-privacy-api-migration-guide/)
for details.
- If `targetType` is 'content', then specify the content ID.
- If `targetType` is 'space', then specify the space key.
required: true
schema:
type: string
- name: sourceStatus
in: query
description: |-
The status of the source. This parameter is only used when the
`sourceType` is 'content'.
schema:
type: string
- name: targetStatus
in: query
description: |-
The status of the target. This parameter is only used when the
`targetType` is 'content'.
schema:
type: string
- name: sourceVersion
in: query
description: |-
The version of the source. This parameter is only used when the
`sourceType` is 'content' and the `sourceStatus` is 'historical'.
schema:
type: integer
format: int32
- name: targetVersion
in: query
description: |-
The version of the target. This parameter is only used when the
`targetType` is 'content' and the `targetStatus` is 'historical'.
schema:
type: integer
format: int32
- name: expand
in: query
description: |-
A multi-value parameter indicating which properties of the response
object to expand.
- `relationData` returns information about the relationship, such as
who created it and when it was created.
- `source` returns the source entity.
- `target` returns the target entity.
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- relationData
- source
- target
- name: start
in: query
description: The starting index of the returned relationships.
schema:
minimum: 0
type: integer
format: int32
default: 0
- name: limit
in: query
description: |-
The maximum number of relationships to return per page.
Note, this may be restricted by fixed system limits.
schema:
minimum: 0
type: integer
format: int32
default: 25
responses:
'200':
description: Returned if the requested relationships are returned.
content:
application/json:
schema:
$ref: '#/components/schemas/RelationArray'
'400':
description: Returned if the request is invalid.
content: {}
'403':
description: |-
Returned if the user does not have permission to view the
relationship
content: {}
'404':
description: Returned if the target entity does not exist.
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- read:confluence-content.summary
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- read:confluence-content.summary
- scheme: oAuthDefinitions
state: Beta
scopes:
- read:relation:confluence
- read:content-details:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-connect-scope: READ
components:
schemas:
RelationArray:
required:
- _links
- limit
- results
- size
- start
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/Relation'
start:
type: integer
format: int32
limit:
type: integer
format: int32
size:
type: integer
format: int32
_links:
$ref: '#/components/schemas/GenericLinks'
Relation:
required:
- _links
- name
type: object
properties:
name:
type: string
relationData:
$ref: '#/components/schemas/RelationData'
source:
oneOf:
- $ref: '#/components/schemas/Content'
- $ref: '#/components/schemas/User'
- $ref: '#/components/schemas/Space'
target:
oneOf:
- $ref: '#/components/schemas/Content'
- $ref: '#/components/schemas/User'
- $ref: '#/components/schemas/Space'
_expandable:
type: object
properties:
relationData:
type: string
source:
type: string
target:
type: string
_links:
$ref: '#/components/schemas/GenericLinks'
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).
Responses that return an error status code will also return a response
body, similar to the following:
```json
{
"statusCode": 404,
"data": {
"authorized": false,
"valid": false,
# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/atlassian/refs/heads/main/openapi/atlassian-wiki-rest-api-relation--openapi-original.yml