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.
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
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.
<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>
{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.
A service providing search results using the Confluence search with various parameters.
Search Confluence using the given parameters.
parameter | value | description |
---|---|---|
query |
||
type |
||
search |
Default: site |
|
startIndex |
Default: 0 |
|
pageSize |
||
max-results |
||
spaceKey |
||
attachmentType |
||
label |
||
groupResults |
Default: true |
|
searchParentName |
Default: false |
|
preferredSpaceKey |
available response representations:
Results matching criteria. Depending on parameters the results are either in groups (quick search) or results (full search) fields.
Source: schema1.xsd
<xs:complexType name="searchResultEntityList"> <xs:sequence> <xs:element name="result" type="searchResultEntity" maxOccurs="unbounded" minOccurs="0"/> <xs:element ref="group" maxOccurs="unbounded" minOccurs="0"/> <xs:element name="totalSize" type="xs:int"/> </xs:sequence> </xs:complexType>
Site wide Confluence search.
parameter | value | description |
---|---|---|
query |
query string |
|
type |
content types to search for |
|
spaceKey |
keys of spaces to search in, if not specified it searches in all spaces |
|
attachmentType |
attachment types to search in, if not specified it searches all attachments |
|
label |
start index of search results |
|
startIndex |
Default: 0 |
max page size of search results |
pageSize |
Filters the results for content with the specified labels, if not specified all results are returned |
available response representations:
Search is performed on the name of content only e.g. title of page, name of attachment
parameter | value | description |
---|---|---|
query |
||
type |
||
spaceKey |
||
attachmentType |
||
label |
||
groupResults |
Default: true |
|
searchParentName |
Default: false |
|
preferredSpaceKey |
||
startIndex |
Default: 0 |
|
pageSize |
available response representations:
Returns the UserSessionEntity for the user making the request. Example URL: http://host/confluence/rest/prototype/1/session
available response representations:
<?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"/>
</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"/>
</content>
</history>
</session>
A UserSessionEntity. By default the history is not expanded.
Source: schema1.xsd
<xs:complexType name="userSessionEntity"> <xs:sequence> <xs:element name="history" type="contentEntityList" minOccurs="0"/> </xs:sequence> <xs:attribute name="expand" type="xs:string"/> </xs:complexType>
Returns the UserHistoryList for the user making the request. Example URL: http://host/confluence/rest/prototype/1/session/history
parameter | value | description |
---|---|---|
start-index |
The first (inclusive) index to return. Can be any integer zero or greater. |
|
max-results |
The number of results to return. Can be any positive integer. |
available response representations:
<?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"/>
</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"/>
</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).
This method will always return HTTP 404 (not found) as it can not find attachments without an ID.
available response representations:
This method will always return HTTP 404 (not found) as it can not find attachments without an ID.
parameter | value | description |
---|---|---|
id |
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:
Returned if the requested attachment is not found, or the user does not have permission to see it
<?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.
Source: schema1.xsd
<xs:complexType name="attachmentEntity"> <xs:complexContent> <xs:extension base="searchResultEntity"> <xs:sequence> <xs:element name="ownerId" type="xs:string" minOccurs="0"/> <xs:element name="parentTitle" type="xs:string" minOccurs="0"/> <xs:element ref="link" maxOccurs="unbounded" minOccurs="0"/> <xs:element name="title" type="xs:string" minOccurs="0"/> <xs:element name="thumbnailLink" type="link" minOccurs="0"/> <xs:element name="thumbnailWidth" type="xs:int"/> <xs:element name="thumbnailHeight" type="xs:int"/> <xs:element name="wikiLink" type="xs:string" minOccurs="0"/> <xs:element ref="space" minOccurs="0"/> <xs:element name="lastModifiedDate" type="dateEntity" minOccurs="0"/> <xs:element name="createdDate" type="dateEntity" minOccurs="0"/> </xs:sequence> <xs:attribute name="type" type="xs:string"/> <xs:attribute name="fileName" type="xs:string"/> <xs:attribute name="contentType" type="xs:string"/> <xs:attribute name="fileSize" type="xs:long" use="required"/> <xs:attribute name="niceFileSize" type="xs:string"/> <xs:attribute name="comment" type="xs:string"/> <xs:attribute name="version" type="xs:int" use="required"/> <xs:attribute name="niceType" type="xs:string"/> <xs:attribute name="iconClass" type="xs:string"/> </xs:extension> </xs:complexContent> </xs:complexType>
Rest resource for accessing Confluence content. Currently supports only read access for pages, blogs and comments.
Returns HTTP 404 (not found) as there is no content to return if no ID is passed.
available response representations:
Always returned as no content can be retrieved without ID.
parameter | value | description |
---|---|---|
id |
Returns the content for the given ID.
available response representations:
Returned if the requested content is not found, or the user does not have permission to see it
<?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"/>
<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] &
[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.
Source: schema1.xsd
<xs:complexType name="contentEntity"> <xs:complexContent> <xs:extension base="searchResultEntity"> <xs:sequence> <xs:element ref="link" maxOccurs="unbounded" minOccurs="0"/> <xs:element name="title" type="xs:string" minOccurs="0"/> <xs:element name="parentId" type="xs:string" minOccurs="0"/> <xs:element name="wikiLink" type="xs:string" minOccurs="0"/> <xs:element name="lastModifiedDate" type="dateEntity" minOccurs="0"/> <xs:element name="createdDate" type="dateEntity" minOccurs="0"/> <xs:element ref="space" minOccurs="0"/> <xs:element name="children" type="contentEntityList" minOccurs="0"/> <xs:element ref="comments" minOccurs="0"/> <xs:element ref="body" minOccurs="0"/> <xs:element ref="attachments" minOccurs="0"/> <xs:element ref="labels" minOccurs="0"/> <xs:element name="creator" type="userEntity" minOccurs="0"/> <xs:element name="lastModifier" type="userEntity" minOccurs="0"/> <xs:element name="username" type="xs:string" minOccurs="0"/> <xs:element name="thumbnailLink" type="link" minOccurs="0"/> </xs:sequence> <xs:attribute name="expand" type="xs:string"/> <xs:attribute name="type" type="xs:string"/> </xs:extension> </xs:complexContent> </xs:complexType>
parameter | value | description |
---|---|---|
id |
ID of resource (such as a page or blog post) |
Returns the attachments for a given resource. The results are ordered by the creation date.
parameter | value | description |
---|---|---|
start-index |
Index of first item (inclusive) to return. |
|
max-results |
Maximum number of items to return. Default is 50. |
|
mimeType |
Mime types to filter the attachments by, such as: image/jpeg |
|
attachmentType |
'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 |
Default: false |
set to true to have the results returned in reverse chronological order. |
available response representations:
Returned if the requested content item is not found, or the user does not have permission to see it
<?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.
Source: schema1.xsd
<xs:complexType name="attachmentEntity"> <xs:complexContent> <xs:extension base="searchResultEntity"> <xs:sequence> <xs:element name="ownerId" type="xs:string" minOccurs="0"/> <xs:element name="parentTitle" type="xs:string" minOccurs="0"/> <xs:element ref="link" maxOccurs="unbounded" minOccurs="0"/> <xs:element name="title" type="xs:string" minOccurs="0"/> <xs:element name="thumbnailLink" type="link" minOccurs="0"/> <xs:element name="thumbnailWidth" type="xs:int"/> <xs:element name="thumbnailHeight" type="xs:int"/> <xs:element name="wikiLink" type="xs:string" minOccurs="0"/> <xs:element ref="space" minOccurs="0"/> <xs:element name="lastModifiedDate" type="dateEntity" minOccurs="0"/> <xs:element name="createdDate" type="dateEntity" minOccurs="0"/> </xs:sequence> <xs:attribute name="type" type="xs:string"/> <xs:attribute name="fileName" type="xs:string"/> <xs:attribute name="contentType" type="xs:string"/> <xs:attribute name="fileSize" type="xs:long" use="required"/> <xs:attribute name="niceFileSize" type="xs:string"/> <xs:attribute name="comment" type="xs:string"/> <xs:attribute name="version" type="xs:int" use="required"/> <xs:attribute name="niceType" type="xs:string"/> <xs:attribute name="iconClass" type="xs:string"/> </xs:extension> </xs:complexContent> </xs:complexType>
REST resource for getting displayable breadcrumbs for confluence content
Gets the breadcrumbs to display for the given content id and type.
parameter | value | description |
---|---|---|
id |
Default: -1 |
|
type |
available response representations:
parameter | value | description |
---|---|---|
username |
Rest resource for accessing Confluence spaces. Currently supports only read access to spaces.
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.
parameter | value | description |
---|---|---|
type |
Default: all |
The space type parameter to filter the list by. Type can be one of: GLOBAL, PERSONAL, ALL |
start-index |
The first (inclusive) index to return. Can be any integer zero or greater. |
|
max-results |
The number of results to return. Can be any positive integer. |
|
spaceKey |
a list of space keys to view |
available response representations:
<?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"/>
</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"/>
</home>
</space>
</spaces>
A list of spaces
Source: schema1.xsd
<xs:complexType name="spaceEntityList"> <xs:sequence> <xs:element ref="space" maxOccurs="unbounded" minOccurs="0"/> </xs:sequence> <xs:attribute name="expand" type="xs:string"/> </xs:complexType>
parameter | value | description |
---|---|---|
key |
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:
Response when the requested space does not exist or the user requesting it does not have sufficent rights to see it.
<?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"/>
</home>
</space>
A detailed description of a space.
Source: schema1.xsd
<xs:complexType name="spaceEntity"> <xs:complexContent> <xs:extension base="searchResultEntity"> <xs:sequence> <xs:element ref="link" maxOccurs="unbounded" minOccurs="0"/> <xs:element name="description" type="xs:string" minOccurs="0"/> <xs:element name="lastModifiedDate" type="dateEntity" minOccurs="0"/> <xs:element name="createdDate" type="dateEntity" minOccurs="0"/> <xs:element name="wikiLink" type="xs:string" minOccurs="0"/> <xs:element name="rootpages" type="contentEntityList" minOccurs="0"/> <xs:element ref="userproperties" minOccurs="0"/> <xs:element name="home" type="contentEntity" minOccurs="0"/> </xs:sequence> <xs:attribute name="expand" type="xs:string"/> <xs:attribute name="key" type="xs:string"/> <xs:attribute name="name" type="xs:string"/> <xs:attribute name="title" type="xs:string"/> <xs:attribute name="type" type="xs:string"/> </xs:extension> </xs:complexContent> </xs:complexType>
Rest resource for accessing translations in Confluence.
Returns the text for the given plugin keys.
parameter | value | description |
---|---|---|
pluginKeys |
available response representations:
parameter | value | description |
---|---|---|
key |
The plugin key as it is defined in the atlassian-plugin.xml. |
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: