The Confluence Cloud REST API

Search

Search content

GET /wiki/rest/api/search

Searches for content using the Confluence Query Language (CQL)

Example initial call:

1
2
/wiki/rest/api/search?cql=type=page&limit=25

Example response:

1
2
{
  "results": [
    { ... },
    { ... },
    ...
    { ... }
  ],
  "limit": 25,
  "size": 25,
  ...
  "_links": {
    "base": "<url>",
    "context": "<url>",
    "next": "/rest/api/search?cql=type=page&limit=25&cursor=raNDoMsTRiNg",
    "self": "<url>"
  }
}

When additional results are available, returns next and prev URLs to retrieve them in subsequent calls. The URLs each contain a cursor that points to the appropriate set of results. Use limit to specify the number of results returned in each call.

Example subsequent call (taken from example response):

1
2
/wiki/rest/api/search?cql=type=page&limit=25&cursor=raNDoMsTRiNg

The response to this will have a prev URL similar to the next in the example response.

Permissions required: Permission to view the entities. Note, only entities that the user has permission to view will be returned.

Connect app scope required: READ

OAuth 2.0 scopes required:

ClassicRECOMMENDED:search:confluence

Granular:read:content-details:confluence

Request

Query parameters

cql Required

string

The CQL query to be used for the search. See Advanced Searching using CQL for instructions on how to build a CQL query.

cqlcontext

string

The space, content, and content status to execute the search against.

spaceKey Key of the space to search against. Optional.
contentId ID of the content to search against. Optional. Must be in the space specified by spaceKey.
contentStatuses Content statuses to search against. Optional.

Specify these values in an object. For example, cqlcontext={%22spaceKey%22:%22TEST%22, %22contentId%22:%22123%22}

cursor

string

Pointer to a set of search results, returned as part of the next or prev URL from the previous search call.

next

boolean

Default: false

prev

boolean

Default: false

limit

integer

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

Default: 25, Minimum: 0, Format: int32

start

integer

The start point of the collection to return

Default: 0, Minimum: 0, Format: int32

includeArchivedSpaces

boolean

Whether to include content from archived spaces in the results.

Default: false

excludeCurrentSpaces

boolean

Whether to exclude current spaces and only show archived spaces.

Default: false

excerpt

string

The excerpt strategy to apply to the result

Default: highlight

Valid values: highlight, indexed, none, highlight_unescaped, indexed_unescaped

sitePermissionTypeFilter

string

Filters users by permission type. Use NONE to default to licensed users, EXTERNALCOLLABORATOR for external/guest users, and ALL to include all permission types.

Default: none

Valid values: all, externalCollaborator, none

integer

Format: int64

expand

Array<string>

Style: form

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/search?cql={cql}`, {
  headers: {
    'Accept': 'application/json'
  }
});

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

Responses

200

400

403

Returned if the requested results are returned.

Content type	Value
application/json	SearchPageResponseSearchResult

Search users

GET /wiki/rest/api/search/user

Searches for users using user-specific queries from the Confluence Query Language (CQL).

Note that some user fields may be set to null depending on the user's privacy settings. These are: email, profilePicture, displayName, and timeZone.

Connect app scope required: READ

OAuth 2.0 scopes required:

read:content-details:confluence

Request

Query parameters

cql Required

string

The CQL query to be used for the search. See Advanced Searching using CQL for instructions on how to build a CQL query.

Example queries: cql=type=user will return all users cql=user="1234" will return user with accountId "1234" You can also use IN, NOT IN, != operators cql=user IN ("12", "34") will return users with accountids "12" and "34" cql=user.fullname~jo will return users with nickname/full name starting with "jo" cql=user.accountid="123" will return user with accountId "123"

start

integer

The starting index of the returned users.

Default: 0, Minimum: 0, Format: int32

limit

integer

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

Default: 25, Minimum: 0, Format: int32

expand

Array<string>

A multi-value parameter indicating which properties of the user to expand.

operations returns the operations for the user, which are used when setting permissions.
personalSpace returns the personal space of the user.

Style: form

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/search/user?cql={cql}`, {
  headers: {
    'Accept': 'application/json'
  }
});

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

Responses

200

400

403

Returned if the requested results are returned.

Content type	Value
application/json	SearchPageResponseSearchResult