This document describes the REST API and resources provided by Confluence. 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. The response format is JSON. 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 the Confluence REST API resource have the following structure:
With context: http://host:port/context/rest/api/resource-name
Or without context: http://host:port/rest/api/resource-name
Example with context: http://example.com:8080/confluence/rest/api/space/ds
Example without context: http://confluence.myhost.com:8095/rest/api/space/ds
In order to 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
.
You can use the .
dot notation to specify expansion of entities within another entity. For example
body.view
would expand the content body
and expand the view
rendering of
it.
parameter | value | description |
---|---|---|
id |
a string containing the id of the content to retrieve children for |
The {@link ContentType}(s) of the children returned is specified by the "expand" query parameter in the request
- this parameter can include expands for multiple child types.
If no types are included in the expand parameter, the map returned will just list the child types that are available
to be expanded for the {@link Content} referenced by the "id" path parameter.
Example request URI(s):
http://example.com/rest/api/content/1234/children
http://example.com/rest/api/content/1234/children?expand=page.body.VIEW
http://example.com/rest/api/content/1234/children?expand=page&start=20&limit=10
parameter | value | description |
---|---|---|
expand |
Default: |
a comma separated list of properties to expand on the children |
available response representations:
available response representations:
parameter | value | description |
---|---|---|
id |
a string containing the id of the content to retrieve children for | |
id |
a string containing the id of the content to retrieve children for | |
type |
a {@link ContentType} to filter children on. |
The {@link ContentType}(s) of the children returned is specified by the "type" path parameter in the request.
Example request URI(s):
http://example.com/rest/api/content/1234/children/page
http://example.com/rest/api/content/1234/children/comment
http://example.com/rest/api/content/1234/children/page?expand=body.VIEW
http://example.com/rest/api/content/1234/children/comment?start=20&limit=10
parameter | value | description |
---|---|---|
expand |
Default: |
a comma separated list of properties to expand on the children |
start |
(optional, default: 0) the index of the first item within the result set that should be returned | |
limit |
Default: 25 |
(optional, default: site limit) how many items should be returned after the start index |
available response representations:
available response representations:
Returns information about a number of spaces.
Example request URI(s):
http://example.com/rest/api/space?spaceKey=TST&spaceKey=ds
parameter | value | description |
---|---|---|
spaceKey |
a list of space keys | |
expand |
Default: |
a comma separated list of properties to expand on the spaces |
start |
the start point of the collection to return | |
limit |
Default: 25 |
the limit of the number of spaces to return, this may be restricted by fixed system limits |
available response representations:
available response representations:
parameter | value | description |
---|---|---|
spaceKey |
a string containing the key of the space |
Returns the content in this given space
Example request URI(s):
http://example.com/rest/api/space/TEST/content?expand=history
parameter | value | description |
---|---|---|
depth |
Default: all |
a string indicating if all content, or just the root content of the space is returned. Default value: all . Valid
values: all, root .
|
expand |
Default: |
a comma separated list of properties to expand on each piece of content retrieved |
start |
the start point of the collection to return | |
limit |
Default: 25 |
the limit of the number of labels to return, this may be restricted by fixed system limits |
available response representations:
available response representations:
parameter | value | description |
---|---|---|
spaceKey |
a string containing the key of the space |
Returns information about a space.
Example request URI(s):
http://example.com/rest/api/space/TST?expand=description
parameter | value | description |
---|---|---|
expand |
Default: |
a comma separated list of properties to expand on the space |
available response representations:
available response representations:
The incoming Space does not include an id, but must include a Key and Name, and should include a Description.
acceptable request representations:
available response representations:
parameter | value | description |
---|---|---|
spaceKey |
a string containing the key of the space | |
type |
the type of content to return with the space. Valid values: page, blogpost . |
Returns the content in this given space with the given type
Example request URI(s):
http://example.com/rest/api/space/TEST/content/page?expand=history
parameter | value | description |
---|---|---|
depth |
Default: all |
a string indicating if all content, or just the root content of the space is returned. Default value: all . Valid
values: all, root .
|
expand |
Default: |
a comma separated list of properties to expand on each piece of content retrieved |
start |
the start point of the collection to return | |
limit |
Default: 25 |
the limit of the number of labels to return, this may be restricted by fixed system limits |
available response representations:
available response representations:
parameter | value | description |
---|---|---|
to |
the representation to convert to |
Converts between content body representations.
Not all representations can be converted to/from other formats. Supported conversions:
Source Representation | Destination Representation Supported |
---|---|
storage | view,export_view,editor |
editor | storage |
view | None |
export_view | None |
Example request URI(s):
http://example.com/rest/api/contentbody/convert/view
acceptable request representations:
available response representations:
parameter | value | description |
---|---|---|
id |
A string containing the id of the labels content container |
Returns the list of labels on a piece of Content.
Example request URI(s):
http://example.com/rest/api/content/1234/labels
http://example.com/rest/api/content/1234/labels?prefix=global&start=0&limit=200
parameter | value | description |
---|---|---|
prefix |
the prefixes to filter the labels with {@see Label.Prefix} | |
start |
the start point of the collection to return | |
limit |
Default: 200 |
the limit of the number of labels to return, this may be restricted by fixed system limits |
available response representations:
available response representations:
Adds a list of labels to the specified content.
The body is the json representation of the list.
Example body:
[ { "prefix": "global", "name": "label2" },
{ "prefix": "global", "name": "label2" } ]
acceptable request representations:
available response representations:
available response representations:
parameter | value | description |
---|---|---|
id |
a string containing the id of the content to retrieve descendants for |
The {@link ContentType}(s) of the descendants returned is specified by the "expand" query parameter in the request
- this parameter can include expands for multiple descendant types.
If no types are included in the expand parameter, the map returned will just list the descendant types that are available
to be expanded for the {@link Content} referenced by the "id" path parameter.
Currently the only supported descendants are comment descendants of non-comment Content.
Example request URI(s):
http://example.com/rest/api/content/1234/descendant
http://example.com/rest/api/content/1234/descendant?expand=comment.body.VIEW
http://example.com/rest/api/content/1234/descendant?expand=comment&start=20&limit=10
parameter | value | description |
---|---|---|
expand |
Default: |
a comma separated list of properties to expand on the descendants |
available response representations:
available response representations:
parameter | value | description |
---|---|---|
id |
a string containing the id of the content to retrieve descendants for | |
id |
a string containing the id of the content to retrieve descendants for | |
type |
a {@link ContentType} to filter descendants on. |
The {@link ContentType}(s) of the descendants returned is specified by the "type" path parameter in the request.
Currently the only supported descendants are comment descendants of non-comment Content.
Example request URI(s):
http://example.com/rest/api/content/1234/descendant/comment
http://example.com/rest/api/content/1234/descendant/comment?expand=body.VIEW
http://example.com/rest/api/content/1234/descendant/comment?start=20&limit=10
parameter | value | description |
---|---|---|
expand |
Default: |
a comma separated list of properties to expand on the descendants |
start |
(optional, default: 0) the index of the first item within the result set that should be returned | |
limit |
Default: 25 |
(optional, default: site limit) how many items should be returned after the start index |
available response representations:
available response representations:
parameter | value | description |
---|---|---|
id |
a string containing the id of the attachments content container |
Returns a paginated list of attachment Content entities within a single container.
Example request URI(s):
http://example.com/rest/api/content/1234/attachments?start=0&limit=10
http://example.com/rest/api/content/1234/attachments?filename=myfile.txt&expand=version,container
parameter | value | description |
---|---|---|
expand |
Default: |
a comma separated list of properties to expand on the Attachments returned. Optional. |
start |
the index of the first item within the result set that should be returned. Optional. | |
limit |
Default: 50 |
how many items should be returned after the start index. Optional. |
filename |
(optional) filter parameter to return only the Attachment with the matching file name. Optional. | |
mediaType |
(optional) filter parameter to return only Attachments with a matching Media-Type. Optional. |
available response representations:
available response representations:
Add one or more attachments to a Confluence Content entity, with optional comments.
Comments are optional, but if included there must be as many comments as there are files, and the comments must be in the same order as the files.
This resource expects a multipart post. The media-type multipart/form-data is defined in RFC 1867. Most client libraries have classes that make dealing with multipart posts simple. For instance, in Java the Apache HTTP Components library provides a MultiPartEntity that makes it simple to submit a multipart POST.
In order to protect against XSRF attacks, because this method accepts multipart/form-data, it has XSRF protection on it. This means you must submit a header of X-Atlassian-Token: nocheck with the request, otherwise it will be blocked.
The name of the multipart/form-data parameter that contains attachments must be "file"
A simple example to attach a file called "myfile.txt" to the container with id "123", with a comment included:
curl -D- -u admin:admin -X POST -H "X-Atlassian-Token: nocheck" -F "file=@myfile.txt;comment=This is my File" http://myhost/rest/api/1/content/123/attachments
A example to attach a file called "myfile.txt" to the container with id "123", with a comment, and set the minorEdits flag to be true:
curl -D- -u admin:admin -X POST -H "X-Atlassian-Token: nocheck" -F "file=@myfile.txt;minorEdit=true;comment=This is my File" http://myhost/rest/api/1/content/123/attachments
An example to upload the same file, with no comment:
curl -D- -u admin:admin -X POST -H "X-Atlassian-Token: nocheck" -F "file=@myfile.txt" http://myhost/rest/api/1/content/123/attachments/456/data
Example request URI(s):
http://example.com/rest/api/content/1234/attachments
available response representations:
available response representations:
available response representations:
parameter | value | description |
---|---|---|
id |
a string containing the id of the attachments content container | |
attachmentId |
the id of the attachment to update |
Update the non-binary data of an Attachment.
This resource can be used to update an attachment's filename, media-type, comment, and parent container.
Example request URI(s):
http://example.com/rest/api/content/1234/attachments/5678
acceptable request representations:
available response representations:
available response representations:
available response representations:
available response representations:
available response representations:
parameter | value | description |
---|---|---|
id |
a string containing the id of the attachments content container | |
attachmentId |
the id of the attachment to upload a new file for |
Update the binary data of an Attachment, and optionally the comment.
Comments are optional, but if included there must be as many comments as there are files, and the comments must be in the same order as the files.
This resource expects a multipart post. The media-type multipart/form-data is defined in RFC 1867. Most client libraries have classes that make dealing with multipart posts simple. For instance, in Java the Apache HTTP Components library provides a MultiPartEntity that makes it simple to submit a multipart POST.
In order to protect against XSRF attacks, because this method accepts multipart/form-data, it has XSRF protection on it. This means you must submit a header of X-Atlassian-Token: nocheck with the request, otherwise it will be blocked.
The name of the multipart/form-data parameter that contains attachments must be "file"
A simple example to upload a file called "myfile.txt" to the Attachment with id "456" in a container with id "123", with the comment updated, and minorEdit set to true:
curl -D- -u admin:admin -X POST -H "X-Atlassian-Token: nocheck" -F "file=@myfile.txt;minorEdit=true;comment=This is my updated File" http://myhost/rest/api/1/content/123/attachments/456/data
An example to upload the same file, with no comment:
curl -D- -u admin:admin -X POST -H "X-Atlassian-Token: nocheck" -F "file=@myfile.txt" http://myhost/rest/api/1/content/123/attachments/456/data
Example request URI(s):
http://example.com/rest/api/content/1234/attachments/5678/data
available response representations:
available response representations:
available response representations:
Returns a piece of Content. EXPERIMENTAL: only implemented for pages and blogposts
Example request URI(s):
http://example.com/rest/api/content?spaceKey=TST&Title=Cheese&expand=space,body.view,version,container
http://example.com/rest/api/content?type=blogpost&spaceKey=TST&title=Bacon&postingDay=2014-02-13&expand=space,body.view,version,container
parameter | value | description |
---|---|---|
type |
Default: page |
the content type to return. Default value: page . Valid values: page, blogpost . |
spaceKey |
the space key to find content under. Required. | |
title |
the title of the page to find. Required for page type. |
|
postingDay |
the posting day of the blog post. Required for blogpost type. Format: yyyy-mm-dd . Example: 2013-02-13 |
|
expand |
Default: |
a comma separated list of properties to expand on the content. Default value: history,space,version . |
start |
the start point of the collection to return | |
limit |
Default: 25 |
the limit of the number of items to return, this may be restricted by fixed system limits |
available response representations:
available response representations:
parameter | value | description |
---|---|---|
id |
the id of the content |
Deletes a piece of Content.
Updates a piece of Content.
The body contains the representation of the content.
acceptable request representations:
available response representations:
available response representations:
Returns a piece of Content.
Example request URI(s):
http://example.com/rest/api/content/1234?expand=space,body.view,version,container
parameter | value | description |
---|---|---|
expand |
Default: history,space,version |
A comma separated list of properties to expand on the content. Default value: history,space,version |
available response representations:
available response representations:
parameter | value | description |
---|---|---|
id |
the id of the content |
Returns the history of a particular piece of content
Example request URI(s):
http://example.com/rest/api/content/1234/history
parameter | value | description |
---|---|---|
expand |
Default: |
the properties on content history to expand |
available response representations:
available response representations:
parameter | value | description |
---|---|---|
id |
a string containing the id of the content | |
hash |
the hash of the macro body | |
version |
the version of the content which the hash belongs |
Returns the body of a macro (in storage format) with the given hash. This resource is primarily used by connect applications that require the body of macro to perform their work.
The hash is generated by connect during render time of the local macro holder and is usually only relevant during the scope of one request. For optimisation purposes, this hash will usually live for multiple requests.
available response representations:
available response representations: