The Confluence Cloud REST API

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 /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.

Connect app scope required: READ

OAuth scopes required: read:relation:confluence, read:content-details:confluence

DEPRECATED OAuth scopes: read:confluence-content.summary
Learn more about deprecated scopes

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 'like' or '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

Forge

cURL

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

const response = await api.asApp().requestConfluence(route`/wiki/rest/api/relation/{relationName}/from/{sourceType}/{sourceKey}/to/{targetType}`, {
  headers: {
    'Accept': 'application/json'
  }
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());

Responses

200

400

403

404

Returned if the requested relationships are returned.

Content type	Value
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 /wiki/rest/api/relation/favourite/from/user/current/to/content/123

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

Connect app scope required: READ

OAuth scopes required: read:relation:confluence, read:content-details:confluence

DEPRECATED OAuth scopes: read:confluence-content.summary
Learn more about deprecated scopes

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

Forge

cURL

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

const response = await api.asApp().requestConfluence(route`/wiki/rest/api/relation/{relationName}/from/{sourceType}/{sourceKey}/to/{targetType}/{targetKey}`, {
  headers: {
    'Accept': 'application/json'
  }
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());

Responses

200

400

401

403

404

Returned if the relationship exists.

Content type	Value
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 /wiki/rest/api/relation/sibling/from/content/123/to/content/456

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

Connect app scope required: WRITE

OAuth scopes required: read:relation:confluence, read:space:confluence, read:user:confluence, read:content:confluence, write:relation:confluence

DEPRECATED OAuth scopes: write:confluence-content
Learn more about deprecated scopes

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

Forge

cURL

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

const response = await api.asApp().requestConfluence(route`/wiki/rest/api/relation/{relationName}/from/{sourceType}/{sourceKey}/to/{targetType}/{targetKey}`, {
  method: 'PUT',
  headers: {
    'Accept': 'application/json'
  }
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());

Responses

200

400

401

403

404

Returned if the relationship is created.

Content type	Value
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.

Connect app scope required: WRITE

OAuth scopes required: write:relation:confluence

DEPRECATED OAuth scopes: write:confluence-content
Learn more about deprecated scopes

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

Forge

cURL

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

const response = await api.asApp().requestConfluence(route`/wiki/rest/api/relation/{relationName}/from/{sourceType}/{sourceKey}/to/{targetType}/{targetKey}`, {
  method: 'DELETE'
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.text());

Responses

204

400

401

403

404

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

A schema has not been defined for this response code.

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 /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.

Connect app scope required: READ

OAuth scopes required: read:relation:confluence, read:content-details:confluence

DEPRECATED OAuth scopes: read:confluence-content.summary
Learn more about deprecated scopes

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 'like' or '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

Forge

cURL

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

const response = await api.asApp().requestConfluence(route`/wiki/rest/api/relation/{relationName}/to/{targetType}/{targetKey}/from/{sourceType}`, {
  headers: {
    'Accept': 'application/json'
  }
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());

Responses

200

400

403

404

Returned if the requested relationships are returned.

Content type	Value
application/json	RelationArray