Confluence Cloud Developer

Confluence Cloud Developer

Rate this page:

Relation

Find target entities related to a source entity

GET /wiki/rest/api/relation/{relationName}/from/{sourceType}/{sourceKey}/to/{targetType}

Returns all target entities that have a particular relationship to the source entity. Note, relationships are one way.

For example, the following method finds all content that the current user has an 'ignore' relationship with: GET https://your-domain.atlassian.net/wiki/rest/api/relation/ignore/from/user/current/to/content Note, 'ignore' is an example custom relationship type.

Permissions required: Permission to view both the target entity and source entity.

App scope required: READ

OAuth scopes required: 
read:confluence-content.summary

Request

Path parameters
relationName Required

string

The name of the relationship. This method supports relationships created via Create relationship. Note, this method does not support 'favourite' relationships.

sourceType Required

string

The source entity type of the relationship.

Valid values: user, content, space

sourceKey Required

string

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 for details.
  • If sourceType is 'content', then specify the content ID.
  • If sourceType is 'space', then specify the space key.
targetType Required

string

The target entity type of the relationship.

Valid values: user, content, space

Query parameters
sourceStatus

string

The status of the source. This parameter is only used when the sourceType is 'content'.

targetStatus

string

The status of the target. This parameter is only used when the targetType is 'content'.

sourceVersion

integer

The version of the source. This parameter is only used when the sourceType is 'content' and the sourceStatus is 'historical'.

Format: int32
targetVersion

integer

The version of the target. This parameter is only used when the targetType is 'content' and the targetStatus is 'historical'.

Format: int32
expand

Array<string>

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

Valid values: relationData, source, target

start

integer

The starting index of the returned relationships.

Default: 0, Minimum: 0, Format: int32
limit

integer

The maximum number of relationships to return per page. Note, this may be restricted by fixed system limits.

Default: 25, Minimum: 0, Format: int32

Example

1
2
3
curl --request GET \
  --url 'https://your-domain.atlassian.net/wiki/rest/api/relation/{relationName}/from/{sourceType}/{sourceKey}/to/{targetType}' \
  --header 'Accept: application/json'

Responses

Returned if the requested relationships are returned.

Content typeValue
application/json

RelationArray

Find relationship from source to target

GET /wiki/rest/api/relation/{relationName}/from/{sourceType}/{sourceKey}/to/{targetType}/{targetKey}

Find whether a particular type of relationship exists from a source entity to a target entity. Note, relationships are one way.

For example, you can use this method to find whether the current user has selected a particular page as a favorite (i.e. 'save for later'): GET https://your-domain.atlassian.net/wiki/rest/api/relation/favourite/from/user/current/to/content/123

Permissions required: Permission to view both the target entity and source entity.

App scope required: READ

OAuth scopes required: 
read:confluence-content.summary

Request

Path parameters
relationName Required

string

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.

sourceType Required

string

The source entity type of the relationship. This must be 'user', if the relationName is 'favourite'.

Valid values: user, content, space

sourceKey Required

string

  • 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 for details.

  • If sourceType is 'content', then specify the content ID.
  • If sourceType is 'space', then specify the space key.
targetType Required

string

The target entity type of the relationship. This must be 'space' or 'content', if the relationName is 'favourite'.

Valid values: user, content, space

targetKey Required

string

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 for details.
  • If targetType is 'content', then specify the content ID.
  • If targetType is 'space', then specify the space key.
Query parameters
sourceStatus

string

The status of the source. This parameter is only used when the sourceType is 'content'.

targetStatus

string

The status of the target. This parameter is only used when the targetType is 'content'.

sourceVersion

integer

The version of the source. This parameter is only used when the sourceType is 'content' and the sourceStatus is 'historical'.

Format: int32
targetVersion

integer

The version of the target. This parameter is only used when the targetType is 'content' and the targetStatus is 'historical'.

Format: int32
expand

Array<string>

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

Valid values: relationData, source, target

Example

1
2
3
curl --request GET \
  --url 'https://your-domain.atlassian.net/wiki/rest/api/relation/{relationName}/from/{sourceType}/{sourceKey}/to/{targetType}/{targetKey}' \
  --header 'Accept: application/json'

Responses

Returned if the relationship exists.

Content typeValue
application/json

Relation

Create relationship

PUT /wiki/rest/api/relation/{relationName}/from/{sourceType}/{sourceKey}/to/{targetType}/{targetKey}

Creates a relationship between two entities (user, space, content). The 'favourite' relationship is supported by default, but you can use this method to create any type of relationship between two entities.

For example, the following method creates a 'sibling' relationship between two pieces of content: GET https://your-domain.atlassian.net/wiki/rest/api/relation/sibling/from/content/123/to/content/456

Permissions required: Permission to access the Confluence site ('Can use' global permission).

App scope required: WRITE

OAuth scopes required: 
write:confluence-content

Request

Path parameters
relationName Required

string

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.

sourceType Required

string

The source entity type of the relationship. This must be 'user', if the relationName is 'favourite'.

Valid values: user, content, space

sourceKey Required

string

  • 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.
targetType Required

string

The target entity type of the relationship. This must be 'space' or 'content', if the relationName is 'favourite'.

Valid values: user, content, space

targetKey Required

string

  • 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.
Query parameters
sourceStatus

string

The status of the source. This parameter is only used when the sourceType is 'content'.

targetStatus

string

The status of the target. This parameter is only used when the targetType is 'content'.

sourceVersion

integer

The version of the source. This parameter is only used when the sourceType is 'content' and the sourceStatus is 'historical'.

Format: int32
targetVersion

integer

The version of the target. This parameter is only used when the targetType is 'content' and the targetStatus is 'historical'.

Format: int32

Example

1
2
3
curl --request PUT \
  --url 'https://your-domain.atlassian.net/wiki/rest/api/relation/{relationName}/from/{sourceType}/{sourceKey}/to/{targetType}/{targetKey}' \
  --header 'Accept: application/json'

Responses

Returned if the relationship is created.

Content typeValue
application/json

Relation

Delete relationship

DELETE /wiki/rest/api/relation/{relationName}/from/{sourceType}/{sourceKey}/to/{targetType}/{targetKey}

Deletes a relationship between two entities (user, space, content).

Permissions required: Permission to access the Confluence site ('Can use' global permission). For favourite relationships, the current user can only delete their own favourite relationships. A space administrator can delete favourite relationships for any user.

App scope required: DELETE

OAuth scopes required: 
write:confluence-content

Request

Path parameters
relationName Required

string

The name of the relationship.

sourceType Required

string

The source entity type of the relationship. This must be 'user', if the relationName is 'favourite'.

Valid values: user, content, space

sourceKey Required

string

  • 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.
targetType Required

string

The target entity type of the relationship. This must be 'space' or 'content', if the relationName is 'favourite'.

Valid values: user, content, space

targetKey Required

string

  • 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.
Query parameters
sourceStatus

string

The status of the source. This parameter is only used when the sourceType is 'content'.

targetStatus

string

The status of the target. This parameter is only used when the targetType is 'content'.

sourceVersion

integer

The version of the source. This parameter is only used when the sourceType is 'content' and the sourceStatus is 'historical'.

Format: int32
targetVersion

integer

The version of the target. This parameter is only used when the targetType is 'content' and the targetStatus is 'historical'.

Format: int32

Example

1
2
curl --request DELETE \
  --url 'https://your-domain.atlassian.net/wiki/rest/api/relation/{relationName}/from/{sourceType}/{sourceKey}/to/{targetType}/{targetKey}'

Responses

Returned if the relationship is deleted or the relationship didn't exist.

Find source entities related to a target entity

GET /wiki/rest/api/relation/{relationName}/to/{targetType}/{targetKey}/from/{sourceType}

Returns all target entities that have a particular relationship to the source entity. Note, relationships are one way.

For example, the following method finds all users that have a 'collaborator' relationship to a piece of content with an ID of '1234': GET https://your-domain.atlassian.net/wiki/rest/api/relation/collaborator/to/content/1234/from/user Note, 'collaborator' is an example custom relationship type.

Permissions required: Permission to view both the target entity and source entity.

App scope required: READ

OAuth scopes required: 
read:confluence-content.summary

Request

Path parameters
relationName Required

string

The name of the relationship. This method supports relationships created via Create relationship. Note, this method does not support 'favourite' relationships.

sourceType Required

string

The source entity type of the relationship.

Valid values: user, content, space

targetType Required

string

The target entity type of the relationship.

Valid values: user, content, space

targetKey Required

string

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 for details.
  • If targetType is 'content', then specify the content ID.
  • If targetType is 'space', then specify the space key.
Query parameters
sourceStatus

string

The status of the source. This parameter is only used when the sourceType is 'content'.

targetStatus

string

The status of the target. This parameter is only used when the targetType is 'content'.

sourceVersion

integer

The version of the source. This parameter is only used when the sourceType is 'content' and the sourceStatus is 'historical'.

Format: int32
targetVersion

integer

The version of the target. This parameter is only used when the targetType is 'content' and the targetStatus is 'historical'.

Format: int32
expand

Array<string>

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

Valid values: relationData, source, target

start

integer

The starting index of the returned relationships.

Default: 0, Minimum: 0, Format: int32
limit

integer

The maximum number of relationships to return per page. Note, this may be restricted by fixed system limits.

Default: 25, Minimum: 0, Format: int32

Example

1
2
3
curl --request GET \
  --url 'https://your-domain.atlassian.net/wiki/rest/api/relation/{relationName}/to/{targetType}/{targetKey}/from/{sourceType}' \
  --header 'Accept: application/json'

Responses

Returned if the requested relationships are returned.

Content typeValue
application/json

RelationArray

Rate this page: