Confluence REST API documentation

This document describes the REST API and resources provided by Confluence wiki. The REST APIs are for developers who want to integrate Confluence into their application and for administrators who want to script interactions with the Confluence server.

Confluence's REST APIs provide access to resources (data entities) via URI paths. To use a REST API, your application will make an HTTP request and parse the response. By default, the response format is XML. If you wish, you can request JSON instead of XML. Your methods will be the standard HTTP methods like GET, PUT, POST and DELETE.

Because the REST API is based on open standards, you can use any web development language to access the API.

Structure of the REST URIs

URIs for a Confluence REST API resource have the following structure:

With context: http://host:port/context/rest/api-name/api-version/resource-name

Or without context: http://host:port/rest/api-name/api-version/resource-name

Currently, the only api-name available is 'prototype'. This is an API that allows basic interactions with a Confluence installation and retrieves information about space and content details.

Example with context: http://myhost.com:8080/confluence/rest/prototype/1/space/ds

Example without context: http://confluence.myhost.com:8095/rest/prototype/1/space/ds

How to use expansion in the REST APIs

In order to be minimise network traffic from the client perspective, our API uses a technique called expansion.

You can use the 'expand' query parameter to specify a comma-separated list of entities that you want expanded, identifying each entity by a given identifier. For example, the value "space,attachments" requests the expansion of entities for which the expand identifier is "space" and "attachments".

To discover the identifiers for each entity, look at the 'expand' attribute in the parent entity. In the XML example below, the page entity declares space, children, comments and attachments as being expandable.

Note: The 'expand' attribute should not be confused with the 'expand' query parameter which specifies which entities you want expanded.

You can use the dot notation to specify expansion of entities within another entity. For example "children.children" would expand the children and the children's children (because its expand identifier is children) and the child entities within the plugin.

If not otherwise indicated, all methods return both XML and JSON. Below are examples of the XML and JSON representations.

XML representation:

[expand]
<content type="page" expand="space,children,comments,attachments" id="6132456">

<link rel="alternate" type="text/html" href="http://localhost:8080/confluence/display/TST/Home"/>

<link rel="alternate" type="applicaton/pdf" href="http://localhost:8080/confluence/spaces/flyingpdf/pdfpageexport.action?pageId=6132456"/>

<link rel="self" href="http://localhost:8080/confluence/rest/prototype/1/content/6132456"/>

<title>Home</title>

<wikiLink>[TST:Home]</wikiLink>

<lastModifiedDate date="2010-03-16T11:50:31+1100" friendly="about 2 hours ago"/>

<createdDate date="2010-03-16T11:50:31+1100" friendly="about 2 hours ago"/>

<space type="space" title="Test Space" name="Test Space" key="TST">

<link rel="self" href="http://localhost:8080/confluence/rest/prototype/1/space/TST"/>

</space>

<children size="0"/>

<comments total="0"/>

<body>

This is the home of the Test Space space. To help you on your way, we've inserted some of our favourite macros on this home page. As you start creating pages, blogging and commenting you'll see the macros below fill up with all the activity in your space.

</body>

<attachments size="0"/>

</content>

The same content in JSON:
[expand]
{id:"6132456",
expand:"space,children,comments,attachments",
type:"page",
link:[{href:"http://localhost:8080/confluence/display/TST/Home",type:"text/html",rel:"alternate"},
  {href:"http://localhost:8080/confluence/spaces/flyingpdf/pdfpageexport.action?pageId=6132456",type:"applicaton/pdf",rel:"alternate"},
  {href:"http://localhost:8080/confluence/rest/prototype/1/content/6132456",rel:"self"}],
title:"Home",
wikiLink:"[TST:Home]",
lastModifiedDate:{friendly:"about 2 hours ago",date:"2010-03-16T11:50:31+1100"},
createdDate:{friendly:"about 2 hours ago",date:"2010-03-16T11:50:31+1100"},
space:{key:"TST",name:"Test Space",title:"Test Space",link:[{href:"http://localhost:8080/confluence/rest/prototype/1/space/TST",rel:"self"}],type:"space"},
children:{size:0},
comments:{total:0},
body:"This is the home of the Test Space space.\n\nTo help you on your way, we've inserted some of our favourite macros on this home page. As you start creating pages, blogging and commenting you'll see the macros below fill up with all the activity in your space.",
attachments:{size:0}}

This document the current REST API provided by Confluence.

Resources

/buildInfo

Methods

GET

available response representations:

/breadcrumb?id&type

REST resource for getting displayable breadcrumbs for confluence content

Methods

GET

Gets the breadcrumbs to display for the given content id and type.

request query parameters
parameter value description

id

long

Default: -1

type

string

available response representations:

  • [expand]

    Returns HTTP 404 (not found) if content for the given id is not found or the user is not permitted to view it.

available response representations:

  • [expand]

    Breadcrumbs for the content to display

/search?query&type&search&startIndex&pageSize&max-results&spaceKey&attachmentType&label&groupResults&searchParentName&preferredSpaceKey

A service providing search results using the Confluence search with various parameters.

Methods

GET

Search Confluence using the given parameters.

request query parameters
parameter value description

query

string

type

string

search

string

Default: site

startIndex

int

Default: 0

pageSize

int

max-results

int

spaceKey

string

attachmentType

string

label

string

groupResults

boolean

Default: true

searchParentName

boolean

Default: false

preferredSpaceKey

string

available response representations:

  • (searchResultEntityList) [expand]

    Results matching criteria. Depending on parameters the results are either in groups (quick search) or results (full search) fields.

    XML Schema

    Source:

/search/site?query&type&spaceKey&attachmentType&label&startIndex&pageSize

Methods

GET

Site wide Confluence search.

request query parameters
parameter value description

query

string

query string

type

string

content types to search for

spaceKey

string

keys of spaces to search in, if not specified it searches in all spaces

attachmentType

string

attachment types to search in, if not specified it searches all attachments

label

string

start index of search results

startIndex

int

Default: 0

max page size of search results

pageSize

int

Filters the results for content with the specified labels, if not specified all results are returned

available response representations:

/search/name?query&type&spaceKey&attachmentType&label&groupResults&searchParentName&preferredSpaceKey&startIndex&pageSize

Methods

GET

Search is performed on the name of content only e.g. title of page, name of attachment

request query parameters
parameter value description

query

string

type

string

spaceKey

string

attachmentType

string

label

string

groupResults

boolean

Default: true

searchParentName

boolean

Default: false

preferredSpaceKey

string

startIndex

int

Default: 0

pageSize

int

available response representations:

/search/user?query&max-results

Methods

GET

User specific search. Searches on username and full name.

request query parameters
parameter value description

query

string

query string

max-results

int

maximum number of search results

available response representations:

/search/group?query&max-results

Methods

GET

Group specific search. Searches on group name.

request query parameters
parameter value description

query

string

The group name (or the start of the group name)

max-results

int

maximum number of search results

available response representations:

/search/user-or-group?query&max-results

Methods

GET

User and group specific search. Searches on username, full name and group name.

request query parameters
parameter value description

query

string

The name (or the start of the name)

max-results

int

maximum number of search results

available response representations:

/space?type&start-index&max-results&spaceKey

Rest resource for accessing Confluence spaces. Currently supports only read access to spaces.

Methods

GET

Retrieves a list of spaces visible to the currently logged in user, alphabetically by space name. An optional parameter 'type' allows filtering on space type. The standard paging parameters 'start-index' and 'max-results' can be used to page through the list. A maximum of 50 (defined by {@link DefaultRestSpaceManager#DEFAULT_MAX_SIZE}) spaces will be listed.

request query parameters
parameter value description

type

string

Default: all

The space type parameter to filter the list by. Type can be one of: GLOBAL, PERSONAL, ALL

start-index

string

The first (inclusive) index to return. Can be any integer zero or greater.

max-results

string

The number of results to return. Can be any positive integer.

spaceKey

string

a list of space keys to view

available response representations:

  • (spaceEntityList) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <spaces>
        <space type="space" title="Demonstration Space" name="Demonstration Space" key="ds" id="1">
            <link rel="self" href="http://localhost"/>
            <link rel="alternate" href="http://localhost"/>
            <description>An example of a Confluence space with a tutorial and sample content.</description>
            <lastModifiedDate date="2009-11-24T13:09:46+1100" friendly="Nov 24"/>
            <createdDate date="2009-11-24T13:09:46+1100" friendly="Nov 24"/>
            <wikiLink>[ds:]</wikiLink>
            <rootpages size="2"/>
            <userproperties/>
            <home type="page">
                <link rel="self" href="http://localhost"/>
                <link rel="alternate" href="http://localhost"/>
                <link rel="alternate" type="application/pdf" href="http://localhost"/>
                <title>Home</title>
                <wikiLink>[ds:Home]</wikiLink>
                <lastModifiedDate date="2009-11-24T13:09:46+1100" friendly="Nov 24"/>
                <createdDate date="2009-11-24T13:09:46+1100" friendly="Nov 24"/>
                <space type="space" title="Demonstration Space" name="Demonstration Space" key="ds">
                    <link rel="self" href="http://localhost"/>
                </space>
            </home>
        </space>
        <space type="space" title="Demonstration Space" name="Demonstration Space" key="ds" id="1">
            <link rel="self" href="http://localhost"/>
            <link rel="alternate" href="http://localhost"/>
            <description>An example of a Confluence space with a tutorial and sample content.</description>
            <lastModifiedDate date="2009-11-24T13:09:46+1100" friendly="Nov 24"/>
            <createdDate date="2009-11-24T13:09:46+1100" friendly="Nov 24"/>
            <wikiLink>[ds:]</wikiLink>
            <rootpages size="2"/>
            <userproperties/>
            <home type="page">
                <link rel="self" href="http://localhost"/>
                <link rel="alternate" href="http://localhost"/>
                <link rel="alternate" type="application/pdf" href="http://localhost"/>
                <title>Home</title>
                <wikiLink>[ds:Home]</wikiLink>
                <lastModifiedDate date="2009-11-24T13:09:46+1100" friendly="Nov 24"/>
                <createdDate date="2009-11-24T13:09:46+1100" friendly="Nov 24"/>
                <space type="space" title="Demonstration Space" name="Demonstration Space" key="ds">
                    <link rel="self" href="http://localhost"/>
                </space>
            </home>
        </space>
    </spaces>
    

    A list of spaces

    XML Schema

    Source:

/space/{key}

resource-wide template parameters
parameter value description

key

string

Methods

GET

Returns information about a space identified by the key passed. ReturnsReturns http HTTP 404 (not found) if the space is not found or the user requesting it does not have the correct permissions.

available response representations:

  • [expand]

    Response when the requested space does not exist or the user requesting it does not have sufficent rights to see it.

available response representations:

  • (spaceEntity) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <space type="space" title="Demonstration Space" name="Demonstration Space" key="ds" id="1">
        <link rel="self" href="http://localhost"/>
        <link rel="alternate" href="http://localhost"/>
        <description>An example of a Confluence space with a tutorial and sample content.</description>
        <lastModifiedDate date="2009-11-24T13:09:46+1100" friendly="Nov 24"/>
        <createdDate date="2009-11-24T13:09:46+1100" friendly="Nov 24"/>
        <wikiLink>[ds:]</wikiLink>
        <rootpages size="2"/>
        <userproperties/>
        <home type="page">
            <link rel="self" href="http://localhost"/>
            <link rel="alternate" href="http://localhost"/>
            <link rel="alternate" type="application/pdf" href="http://localhost"/>
            <title>Home</title>
            <wikiLink>[ds:Home]</wikiLink>
            <lastModifiedDate date="2009-11-24T13:09:46+1100" friendly="Nov 24"/>
            <createdDate date="2009-11-24T13:09:46+1100" friendly="Nov 24"/>
            <space type="space" title="Demonstration Space" name="Demonstration Space" key="ds">
                <link rel="self" href="http://localhost"/>
            </space>
        </home>
    </space>
    

    A detailed description of a space.

    XML Schema

    Source:

/content

Rest resource for accessing Confluence content. Currently supports only read access for pages, blogs and comments.

Methods

GET

Returns HTTP 404 (not found) as there is no content to return if no ID is passed.

available response representations:

  • [expand]

    Always returned as no content can be retrieved without ID.

/content/{id}

resource-wide template parameters
parameter value description

id

long

Methods

GET

Returns the content for the given ID.

available response representations:

  • [expand]

    Returned if the requested content is not found, or the user does not have permission to see it

available response representations:

  • (contentEntity) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <content type="page">
        <link rel="self" href="http://localhost"/>
        <link rel="alternate" href="http://localhost"/>
        <link rel="alternate" type="application/pdf" href="http://localhost"/>
        <title>Home</title>
        <wikiLink>[ds:Home]</wikiLink>
        <lastModifiedDate date="2009-11-24T13:09:46+1100" friendly="Nov 24"/>
        <createdDate date="2009-11-24T13:09:46+1100" friendly="Nov 24"/>
        <space type="space" title="Demonstration Space" name="Demonstration Space" key="ds">
            <link rel="self" href="http://localhost"/>
        </space>
        <body type="0">h1. Demo Area
    
    Confluence is Enterprise [wiki software|http://www.atlassian.com/software/confluence] which extends beyond average wikis. Confluence is available for both [download|http://www.atlassian.com/software/confluence/ConfluenceDownloadCenter.jspa] &amp;
     [hosted|http://www.atlassian.com/software/confluence/hosted.jsp] versions.
    
    
    To get an quick overview, we recommend browsing through the tours suggested above.
    </body>
    </content>
    

    Full representation of the content item.

    XML Schema

    Source:

/content/{id}/attachments?start-index&max-results&mimeType&attachmentType&reverseOrder

resource-wide template parameters
parameter value description

id

long

ID of resource (such as a page or blog post)

Methods

GET

Returns the attachments for a given resource. The results are ordered by the creation date.

request query parameters
parameter value description

start-index

string

Index of first item (inclusive) to return.

max-results

string

Maximum number of items to return. Default is 50.

mimeType

string

Mime types to filter the attachments by, such as: image/jpeg

attachmentType

string

'Nice' type to filter the attachments by. Filtering is case insensititve. Can be one or more of: PDF, IMAGE, XML, HTML, TEXT, WORD, EXCEL, POWERPOINT, JAVA_SOURCE, JAVA_ARCHIVE, ZIP. You can specify multiple types like this: ?attachmentType=image&attachmentType=pdf

reverseOrder

boolean

Default: false

set to true to have the results returned in reverse chronological order.

available response representations:

  • [expand]

    Returned if the requested content item is not found, or the user does not have permission to see it

available response representations:

  • (attachmentEntity) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <attachments size="2">
        <attachment niceType="Image" version="1" comment="Shot of the Harbour Bridge from below" niceFileSize="147 kB" fileSize="150652" contentType="image/jpeg" fileName="harbour bridge3.jpg" type="attachment" id="6488237l">
            <ownerId>6389783</ownerId>
            <link rel="self" href="http://localhost"/>
            <link rel="alternate" href="http://localhost"/>
            <title>harbour bridge3.jpg</title>
            <thumbnailWidth>0</thumbnailWidth>
            <thumbnailHeight>0</thumbnailHeight>
            <wikiLink>[ds:Josh^harbour bridge3.jpg]</wikiLink>
            <space type="space" title="Demonstration Space" name="Demonstration Space" key="ds">
                <link rel="self" href="http://localhost"/>
            </space>
            <lastModifiedDate date="2009-11-24T13:09:46+1100" friendly="Nov 24"/>
            <createdDate date="2009-11-24T13:09:46+1100" friendly="Nov 24"/>
        </attachment>
        <attachment niceType="Image" version="1" comment="Shot of the Harbour Bridge from below" niceFileSize="147 kB" fileSize="150652" contentType="image/jpeg" fileName="harbour bridge3.jpg" type="attachment" id="6488237l">
            <ownerId>6389783</ownerId>
            <link rel="self" href="http://localhost"/>
            <link rel="alternate" href="http://localhost"/>
            <title>harbour bridge3.jpg</title>
            <thumbnailWidth>0</thumbnailWidth>
            <thumbnailHeight>0</thumbnailHeight>
            <wikiLink>[ds:Josh^harbour bridge3.jpg]</wikiLink>
            <space type="space" title="Demonstration Space" name="Demonstration Space" key="ds">
                <link rel="self" href="http://localhost"/>
            </space>
            <lastModifiedDate date="2009-11-24T13:09:46+1100" friendly="Nov 24"/>
            <createdDate date="2009-11-24T13:09:46+1100" friendly="Nov 24"/>
        </attachment>
    </attachments>
    

    Full representation of the attachments with links to download the binary data.

    XML Schema

    Source:

/user

Methods

/user/non-system/{username}

resource-wide template parameters
parameter value description

username

string

Methods

GET

available response representations:

/user/system/anonymous

Methods

GET

available response representations:

/user/current

Methods

GET

available response representations:

/

Methods

GET

Returns an empty page. Note that this method will not even return a valid XML document nor valid JSON.

available response representations:

/session

Methods

GET

Returns the UserSessionEntity for the user making the request. Example URL: http://host/confluence/rest/prototype/1/session

available response representations:

  • (userSessionEntity) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <session>
        <history size="2">
            <content type="page">
                <link rel="self" href="http://localhost"/>
                <link rel="alternate" href="http://localhost"/>
                <link rel="alternate" type="application/pdf" href="http://localhost"/>
                <title>Home</title>
                <wikiLink>[ds:Home]</wikiLink>
                <lastModifiedDate date="2009-11-24T13:09:46+1100" friendly="Nov 24"/>
                <createdDate date="2009-11-24T13:09:46+1100" friendly="Nov 24"/>
                <space type="space" title="Demonstration Space" name="Demonstration Space" key="ds">
                    <link rel="self" href="http://localhost"/>
                </space>
            </content>
            <content type="page">
                <link rel="self" href="http://localhost"/>
                <link rel="alternate" href="http://localhost"/>
                <link rel="alternate" type="application/pdf" href="http://localhost"/>
                <title>Home</title>
                <wikiLink>[ds:Home]</wikiLink>
                <lastModifiedDate date="2009-11-24T13:09:46+1100" friendly="Nov 24"/>
                <createdDate date="2009-11-24T13:09:46+1100" friendly="Nov 24"/>
                <space type="space" title="Demonstration Space" name="Demonstration Space" key="ds">
                    <link rel="self" href="http://localhost"/>
                </space>
            </content>
        </history>
    </session>
    

    A UserSessionEntity. By default the history is not expanded.

    XML Schema

    Source:

/session/check/{username}

resource-wide template parameters
parameter value description

username

string

the user that the remote client thinks they are logged in as. May be blank for an anonymous user.

Methods

GET

Checks that the remote user (from the browser) matches the currently-logged-in user.

available response representations:

/session/history?start-index&max-results

Methods

GET

Returns the UserHistoryList for the user making the request. Example URL: http://host/confluence/rest/prototype/1/session/history

request query parameters
parameter value description

start-index

string

The first (inclusive) index to return. Can be any integer zero or greater.

max-results

string

The number of results to return. Can be any positive integer.

available response representations:

  • [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <history>
        <content type="page">
            <link rel="self" href="http://localhost"/>
            <link rel="alternate" href="http://localhost"/>
            <link rel="alternate" type="application/pdf" href="http://localhost"/>
            <title>Home</title>
            <wikiLink>[ds:Home]</wikiLink>
            <lastModifiedDate date="2009-11-24T13:09:46+1100" friendly="Nov 24"/>
            <createdDate date="2009-11-24T13:09:46+1100" friendly="Nov 24"/>
            <space type="space" title="Demonstration Space" name="Demonstration Space" key="ds">
                <link rel="self" href="http://localhost"/>
            </space>
        </content>
        <content type="page">
            <link rel="self" href="http://localhost"/>
            <link rel="alternate" href="http://localhost"/>
            <link rel="alternate" type="application/pdf" href="http://localhost"/>
            <title>Home</title>
            <wikiLink>[ds:Home]</wikiLink>
            <lastModifiedDate date="2009-11-24T13:09:46+1100" friendly="Nov 24"/>
            <createdDate date="2009-11-24T13:09:46+1100" friendly="Nov 24"/>
            <space type="space" title="Demonstration Space" name="Demonstration Space" key="ds">
                <link rel="self" href="http://localhost"/>
            </space>
        </content>
    </history>
    

    A list of the pages visited by this user. Note that this list does not include calls made via the REST API (such as the content service).

/i18n?pluginKeys

Rest resource for accessing translations in Confluence.

Methods

GET

Returns the text for the given plugin keys.

request query parameters
parameter value description

pluginKeys

string

available response representations:

  • [expand]

    This method will return HTTP 404 (not found) if there are no plugin keys specified

available response representations:

  • [expand]

    A message bundle with all the translated content for the given set of plugin keys.

/i18n/{key}

resource-wide template parameters
parameter value description

key

string

The plugin key as it is defined in the atlassian-plugin.xml.

Methods

GET

Returns the text for the given plugin key. If the specified plugin key does not exist, or the caller does not have permission to access the plugin texts, the response is HTTP 404 (not found). Note that only JSON is returned. An example URL including a plugin key would look like this: http://host/confluence/rest/prototype/1/i18n/com.atlassian.confluence.tinymceplugin

available response representations:

  • [expand]

    Response when the requested resource is not found.

available response representations:

  • [expand]

    A message bundle with all the translated content for the given plugin key.

/attachment

Methods

GET

This method will always return HTTP 404 (not found) as it can not find attachments without an ID.

available response representations:

  • [expand]

    This method will always return HTTP 404 (not found) as it can not find attachments without an ID.

/attachment/{id}

resource-wide template parameters
parameter value description

id

long

Methods

GET

Returns a full representation of the attachment for the given ID. The ID is that of an attachment and not the page it is attached to.

available response representations:

  • [expand]

    Returned if the requested attachment is not found, or the user does not have permission to see it

available response representations:

  • (attachmentEntity) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <attachment niceType="Image" version="1" comment="Shot of the Harbour Bridge from below" niceFileSize="147 kB" fileSize="150652" contentType="image/jpeg" fileName="harbour bridge3.jpg" type="attachment" id="6488237l">
        <ownerId>6389783</ownerId>
        <link rel="self" href="http://localhost"/>
        <link rel="alternate" href="http://localhost"/>
        <title>harbour bridge3.jpg</title>
        <thumbnailWidth>0</thumbnailWidth>
        <thumbnailHeight>0</thumbnailHeight>
        <wikiLink>[ds:Josh^harbour bridge3.jpg]</wikiLink>
        <space type="space" title="Demonstration Space" name="Demonstration Space" key="ds">
            <link rel="self" href="http://localhost"/>
        </space>
        <lastModifiedDate date="2009-11-24T13:09:46+1100" friendly="Nov 24"/>
        <createdDate date="2009-11-24T13:09:46+1100" friendly="Nov 24"/>
    </attachment>
    

    Full representation of the attachment with links to download the binary data.

    XML Schema

    Source: