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. This page documents the REST resources available in Confluence, including the HTTP methods, example request and responses and error codes and messages.
Because the REST API is based on open standards, you can use any web development language to access the API.
We’ve recently moved our Confluence Data Center REST API and it now uses Swagger. This REST API is applicable for Confluence Data Center 9.0 and later. If you’re looking for the REST API for earlier versions of Confluence, visit
Confluence 8.9.3 REST API Documentation.
While we transition our content, note that in some cases documented responses may differ slightly from actual application responses in their response body. We've specifically noticed this in calls that require custom enrichers for processing. For example _links & _expandable are applied at the root level and not to the nested classes in the response body.
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://host:port/confluence/rest/api/space/ds
Example without context: http://host:port/rest/api/space/ds
aliases:
| Applicable | Confluence Server 5.5 - 8.5 Confluence Data Center 5.6 and later |
The Confluence Server and Data Center REST API is for admins who want to script interactions with Confluence Server or Confluence Data Center and developers who want to integrate with or build on top of the Confluence platform.
Using Cloud? Find out about the Confluence Cloud REST API.
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 JSON. Your methods will be the standard HTTP methods: GET, PUT, POST and DELETE. The REST API is based on open standards, so you can use any web development language to access the API.
For some examples of what you can do with the REST API, see Confluence REST API Examples.
Confluence's REST API provides a way to paginate your calls to limit the amount of data you are fetching. Read more about this in Pagination in the REST API.
Confluence's REST API also provides a way to fetch more data in a single call through REST API Expansions. Read more about this in Expansions in the REST API.
Confluence's REST API provides an advanced search that lets you use structured queries to search for content within Confluence. Your search results will take the same form as the Content model returned by the Content REST API.
Content and Space Properties are JSON key-value storages that you can access through the REST API. This is a great way, for example, to store metadata about a piece (or pieces) of content. Read more about Content Properties.
Accessing Confluence using the REST API involves the same authentication and permissions checks that are required when accessing Confluence in your browser. If you don't log in, you are accessing Confluence anonymously. If you log in but don't have permission to view a particular page or space for example, you will not be able to view it using the Confluence REST API either.
For personal use and scripts, you can use basic authentication with either a username and password, or by creating a personal access token (available from Confluence Data Center 7.9).
Read the Atlassian REST API Policy for information on compatibility, versioning and deprecation.
The Atlassian REST API Browser is a tool for discovering the REST APIs available in Atlassian applications, including Confluence. This is available as part of the Atlassian SDK or can be downloaded from the Atlassian Marketplace.
See Using the REST API Browser.
For customers looking to sync their favorite calendar applications with Confluence Team Calendars, we offer CalDAV API.
aliases:
The instructions on this page describe how to define and execute a search using the advanced search capabilities of the Confluence REST API.
An advanced search allows you to use structured queries to search for content in Confluence. Your search results will take the same form as the Content model returned by the Content REST API.
When you perform an advanced search, you use the Confluence Query Language (CQL).
A simple query in CQL (also known as a 'clause') consists of a field, followed by an operator, followed by one or more values or functions. For example, the following simple query will find all content in the "TEST" space. It uses the Space field, the EQUALS operator, and the value "TEST".)
1 2space = "TEST"
It is not possible to compare two fields.
NOTE: CQL gives you some SQL-like syntax, such as the ORDER BY SQL keyword. However, CQL is not a database query language.
For example, CQL does not have a SELECT statement.
Related topics:
The Content API REST Resource now supports CQL as a query parameter to filter the list of returned content.
1 2curl -u username:password http://myhost:8080/rest/api/content/search?cql=space=TEST
The previous example is a simple query, if your query is more complicated you can use the following example:
1 2curl -u username:password -G "http://myhost:8080/context/rest/api/content/search" \ --data-urlencode "cql=(type=page and space=DEV) OR (creator=admin and type=blogpost)" \ | python -m json.tool
To perform an advanced search:
Add your query using the fields, operators, and field values or functions as the value for the CQL query parameter.
Execute a GET request on the resource, you can apply expansions and pagination as you would normally do in the Confluence REST API.
You can use the CONTAINS operator to use Lucene's text-searching features when performing searches on these fields:
For details, see the page on Performing text searches.
To enforce the precedence of operators, you can use parentheses in complex CQL statements.
For example, if you want to find all pages in the Developer space as well as all blog posts created by the the system administrator (bobsmith), you can use parentheses to enforce the precedence of the boolean operators in your query. For example:
1 2(type=page and Space=DEV) OR (creator=bobsmith and type=blogpost)
Note: if you do not use parentheses, the statement will be evaluated left to right.
You can also use parentheses to group clauses, so that you can apply the NOT operator to the group.
A keyword in CQL is a word or phrase that:
See the detailed examples for each keyword next.
Used to combine multiple clauses, allowing you to refine your search.
Note: to control the order in which clauses are executed, you can use parentheses.
Find all blogposts with the label "performance".
1 2label = "performance" and type = "blogpost"
Find all pages created by jsmith in the DEV space.
1 2type = page and creator = jsmith and space = DEV
Find all content that mentions jsmith but was not created by jsmith.
1 2mention = jsmith and creator != jsmith
Used to combine multiple clauses, allowing you to expand your search.
Note: to control the order in which clauses are executed, you can use parentheses. Also see IN, which can be a more convenient way to search for multiple values of a field.)
Find all content in the IDEAS space or with the label idea.
1 2space = IDEAS or label = idea
Find all content last modified before the start of the year or with the label needs\_review.
1 2lastModified < startOfYear() or label = needs_review
Used to negate individual clauses or a complex CQL query (a query made up of more than one clause) using parentheses, allowing you to refine your search.
(Note: also see NOT EQUALS ("!="), DOES NOT CONTAIN ("!~") and NOT IN.)
Find all pages with the "cql" label that aren't in the dev space.
1 2label = cql and not space = dev
Used to specify the fields by whose values the search results will be sorted.
By default, the field's own sorting order is used. You can override this by specifying ascending order ("asc") or descending order ("desc").
Not all fields support ordering. Generally, ordering is not supported where a piece of content can have multiple values for a field, for instance ordering is not supported on labels.
Find content in the DEV space ordered by creation date.
1 2space = DEV order by created
Find content in the DEV space ordered by creation date with the newest first, then title.
1 2space = DEV order by created desc, title
Find pages created by jsmith ordered by created, then title.
1 2creator = jsmith order by created, title asc
CQL Operators
An operator in CQL is one or more symbols or words that compare the value of a field on its left with one or more values (or functions) on its right, such that only true results are retrieved by the clause. Some operators may use the NOT keyword.
List of Operators:
The "=" operator is used to search for content where the value of the specified field exactly matches the specified value. (Note: cannot be used with text fields; see the CONTAINS operator instead.)
To find content where the value of a specified field exactly matches multiple values, use multiple "=" statements with the AND operator.
Find all content that were created by jsmith.
1 2creator = jsmith
Find all content that has the title "Advanced Searching".
1 2title = "Advanced Searching"
The "!=" operator is used to search for content where the value of the specified field does not match the specified value. (Note: cannot be used with text fields; see the DOES NOT MATCH ("!~") operator instead.)
Note: typing field != value is the same as typing NOT field = value.
Find all content in the DEV space that was created by someone other than jsmith.
1 2space = DEV and not creator = jsmith
or:
1 2space = DEV and creator != jsmith
Find all content that was created by me but doesn't mention me.
1 2creator = currentUser() and mention != currentUser()
The ">" operator is used to search for content where the value of the specified field is greater than the specified value.
Cannot be used with text fields.
Note that the ">" operator can only be used with fields which support range operators (e.g. date fields and numeric fields).
To see a field's supported operators, check the individual field reference.
Find all content created in the last 4 weeks.
1 2created > now("-4w")
Find all attachments last modified since the start of the month.
1 2created > startOfMonth() and type = attachment
The ">=" operator is used to search for content where the value of the specified field is greater than or equal to the specified value.
Cannot be used with text fields.
Note that the ">=" operator can only be used with fields which support range operators (e.g. date fields).
To see a field's supported operators, check the individual field reference.
Find all content created on or after 31/12/2008.
1 2created >= "2008/12/31"
The "<" operator is used to search for content where the value of the specified field is less than the specified value. Cannot be used with text fields.
Note that the "<" operator can only be used with fields which support range operators (e.g. date fields). To see a field's supported operators, check the individual field reference.
Find all pages lastModified before the start of the year.
1 2lastModified < startOfYear() and type = page
The "<=" operator is used to search for content where the value of the specified field is less than or equals to the specified value.
Cannot be used with text fields.
Note that the "<=" operator can only be used with fields which support range operators (e.g. date fields). To see a field's supported operators,
check the individual field reference.
Find blog posts created in the since the start of the fortnight.
1 2created >= startOfWeek("-1w") and type = blogpost
The "IN" operator is used to search for content where the value of the specified field is one of multiple specified values.
The values are specified as a comma-delimited list, surrounded by parentheses.
Using "IN" is equivalent to using multiple EQUALS (=) statements with the OR keyword, but is shorter and more convenient.
That is, typing creator IN (tom, jane, harry) is the same as typing creator = "tom" ORcreator = "jane"OR creator = "harry".
Find all content that mentions either jsmith or jbrown or jjones.
1 2mention in (jsmith,jbrown,jjones)
Find all content where the creator or contributor is either Jack or Jill.
1 2creator in (Jack,Jill) or contributor in (Jack,Jill)
The "NOT IN" operator is used to search for content where the value of the specified field is not one of multiple specified values.
Using "NOT IN" is equivalent to using multiple
NOT_EQUALS (!=) statements, but is shorter and more convenient. That is, typing creator NOT IN (tom, jane, harry) is the same as typing creator != "tom" AND creator != "jane" AND creator != "harry".
Find all content where the creator is someone other than Jack, Jill or John.
1 2space = DEV and creator not in (Jack,Jill,John)
The "~" operator is used to search for content where the value of the specified field matches the specified value (either an exact match or a "fuzzy" match -- see examples below). The "~" operator can only be used with text fields, for example:
Note: when using the "~" operator, the value on the right-hand side of the operator can be specified using Confluence text-search syntax.
Find all content where the title contains the word "win" (or simple derivatives of that word, such as "wins").
1 2title ~ win
Find all content where the title contains a wild-card match for the word "win".
1 2title ~ "win*"
Find all content where the text contains the word "advanced" and the word "search".
1 2text ~ "advanced search"
The "!~" operator is used to search for content where the value of the specified field is not a "fuzzy" match for the specified value.
The "!~" operator can only be used with text fields, for example:
Note: when using the "!~" operator, the value on the right-hand side of the operator can be specified using Confluence text-search syntax.
Find all content where the title does not contain the word "run" (or derivatives of that word, such as "running" or "ran").
1 2space = DEV and title !~ run
A field in CQL is a word that represents an indexed property of content in Confluence. In a clause, a field is followed by an operator, that in turn is followed by one or more values (or functions). The operator compares the value of the field with one or more values or functions on the right, such that only true results are retrieved by the clause.
List of Fields:
Search for all pages that are descendants of a given ancestor page. This includes direct child pages and their descendents. It is more general than the parent field.
1 2ancestor
CONTENT
= | != | ~ | !~ | > | >= | < | <= | IN | NOT IN |
|---|---|---|---|---|---|---|---|---|---|
Yes | Yes | No | No | No | No | No | No | Yes | Yes |
None
Find all descendent pages with a given anscestor page.
1 2ancestor = 123
Find descendants of a group of ancestor pages.
1 2ancestor in (123, 456, 789)
Search for content that is contained in the content with the given ID
1 2container
CONTENT
= | != | ~ | !~ | > | >= | < | <= | IN | NOT IN |
|---|---|---|---|---|---|---|---|---|---|
Yes | Yes | No | No | No | No | No | No | Yes | Yes |
None
Find attachments contained in a page with the given content ID.
1 2container = 123 and type = attachment
Find content container in a set of pages with the given IDs.
1 2container in (123, 223, 323)
Search for content that have a given content ID. This is an alias of the ID field.
1 2content
CONTENT
= | != | ~ | !~ | > | >= | < | <= | IN | NOT IN |
|---|---|---|---|---|---|---|---|---|---|
Yes | Yes | No | No | No | No | No | No | Yes | Yes |
None
Find content with a given content ID.
1 2content = 123
Find content in a set of content IDs.
1 2content in (123, 223, 323)
Search for content that was created on, before or after a particular date (or date range).
Note: search results will be relative to your configured time zone (which is by default the Confluence server time zone).
Use one of the following formats:
"yyyy/MM/dd HH:mm"
"yyyy-MM-dd HH:mm"
"yyyy/MM/dd"
"yyyy-MM-dd"
1 2created
DATE
= | != | ~ | !~ | > | >= | < | <= | IN | NOT IN |
|---|---|---|---|---|---|---|---|---|---|
Yes | Yes | No | No | Yes | Yes | Yes | Yes | No | No |
Find content created after the 1st September 2014.
1 2created > 2014/09/01
Find content created in the last 4 weeks.
1 2created >= now("-4w")
Search for content that was created by a particular user. You can search by the user's username.
1 2creator
USER
= | != | ~ | !~ | > | >= | < | <= | IN | NOT IN |
|---|---|---|---|---|---|---|---|---|---|
Yes | Yes | No | No | No | No | No | No | Yes | Yes |
Find content created by jsmith.
1 2created = jsmith
Find content created by john smith or bob nguyen.
1 2created in (jsmith, bnguyen)
Search for content that was created or edited by a particular user. You can search by the user's username.
1 2contributor
USER
= | != | ~ | !~ | > | >= | < | <= | IN | NOT IN |
|---|---|---|---|---|---|---|---|---|---|
Yes | Yes | No | No | No | No | No | No | Yes | Yes |
Find content created by jsmith.
1 2contributor = jsmith
Find content created by john smith or bob nguyen.
1 2contributor in (jsmith, bnguyen)
Search for content that was favorited by a particular user. You can search by the user's username.
Due to security restrictions you are only allowed to filter on the logged in user's favourites. This field is available in both British and American spellings.
1 2favourite
USER
= | != | ~ | !~ | > | >= | < | <= | IN | NOT IN |
|---|---|---|---|---|---|---|---|---|---|
Yes | Yes | No | No | No | No | No | No | Yes | Yes |
Find content that is favorited by the current user.
1 2favourite = currentUser()
Find content favorited by jsmith, where jsmith is also the logged in user.
1 2favourite = jsmith
Search for content that has a given content ID.
1 2id
CONTENT
= | != | ~ | !~ | > | >= | < | <= | IN | NOT IN |
|---|---|---|---|---|---|---|---|---|---|
Yes | Yes | No | No | No | No | No | No | Yes | Yes |
None
Find content with the ID 123.
1 2id = 123
Find content in a set of content IDs.
1 2id in (123, 223, 323)
Search for content that has a particular label.
1 2label
STRING
= | != | ~ | !~ | > | >= | < | <= | IN | NOT IN |
|---|---|---|---|---|---|---|---|---|---|
Yes | Yes | No | No | No | No | No | No | Yes | Yes |
None
Find content that has the label finished.
1 2label = finished
Find content that doesn't have the label draft or review.
1 2label not in (draft, review)
Search for content that was last modified on, before, or after a particular date (or date range).
The search results will be relative to your configured time zone (which is by default the Confluence server time zone).
Use one of the following formats:
"yyyy/MM/dd HH:mm"
"yyyy-MM-dd HH:mm"
"yyyy/MM/dd"
"yyyy-MM-dd"
1 2lastmodified
DATE
= | != | ~ | !~ | > | >= | < | <= | IN | NOT IN |
|---|---|---|---|---|---|---|---|---|---|
Yes | Yes | No | No | Yes | Yes | Yes | Yes | No | No |
Find content that was last modified on 1st September 2014.
1 2lastmodified = 2014-09-01
Find content that was last modified before the start of the year.
1 2lastmodified < startOfYear()
Find content that was last modified on or after 1st September but before 9am on 3rd September 2014.
1 2lastmodified >= 2014-09-01 and lastmodified < "2014-09-03 09:00"
Search for content that has an instance of the macro with the given name in the body of the content.
1 2macro
STRING
= | != | ~ | !~ | > | >= | < | <= | IN | NOT IN |
|---|---|---|---|---|---|---|---|---|---|
Yes | Yes | No | No | No | No | No | No | Yes | Yes |
none
Find content that has the JIRA issue macro.
1 2macro = jira
Find content that has Table of content macro or the widget macro.
1 2macro in (toc, widget)
Search for content that mentions a particular user. You can search by the user's username.
1 2mention
USER
= | != | ~ | !~ | > | >= | < | <= | IN | NOT IN |
|---|---|---|---|---|---|---|---|---|---|
Yes | Yes | No | No | No | No | No | No | Yes | Yes |
Find content that mentions jsmith or kjones.
1 2mention in (jsmith, kjones)
Find content that mentions jsmith.
1 2mention = jsmith
Search for child content of a particular parent page.
1 2parent
CONTENT
= | != | ~ | !~ | > | >= | < | <= | IN | NOT IN |
|---|---|---|---|---|---|---|---|---|---|
Yes | Yes | No | No | No | No | No | No | Yes | Yes |
Find child pages of a parent page with ID 123.
1 2parent = 123
Search for content that is in a particular Space. By default, this searches by space key. You can also search by category, title, and type (see below).
1 2space
SPACE
= | != | ~ | !~ | > | >= | < | <= | IN | NOT IN |
|---|---|---|---|---|---|---|---|---|---|
Yes | Yes | No | No | No | No | No | No | Yes | Yes |
none
Find content in the development space or the QA space.
1 2space in (DEV, QA)
Find content in the development space.
1 2space = DEV
Search for spaces with a particular space category applied. Categories are used to organise spaces in the space directory. Available from Confluence 6.15 and later.
1 2space.category
STRING
= | != | ~ | !~ | > | >= | < | <= | IN | NOT IN |
|---|---|---|---|---|---|---|---|---|---|
Yes | Yes | No | No | No | No | No | No | Yes | Yes |
None
Find spaces that have the category 'development'
1 2space.category = development
Find spaces that don't have the category 'marketing' or 'operations'
1 2space.category not in (marketing, operations)
Search for spaces by space key.
1 2space.key
STRING
= | != | ~ | !~ | > | >= | < | <= | IN | NOT IN |
|---|---|---|---|---|---|---|---|---|---|
Yes | Yes | No | No | No | No | No | No | Yes | Yes |
None
Find the space that has the key 'DEV'
1 2space.key = DEV
Find spaces that have either 'MKT' or 'OPS' or 'DEV'
1 2space.key in (MKT, OPS, DEV)
Search for spaces by title.
1 2space.title
TEXT
= | != | ~ | !~ | > | >= | < | <= | IN | NOT IN |
|---|---|---|---|---|---|---|---|---|---|
No | No | Yes | Yes | No | No | No | No | No | No |
None
Find spaces with titles that match 'Development Team' (fuzzy match)
1 2space.title ~ "Development Team"
Find spaces with titles that don't match "Project" (fuzzy match)
1 2space.title !~ "Project"
Search for spaces of a particular type. Supported content types are:
1 2space.type
TYPE
= | != | ~ | !~ | > | >= | < | <= | IN | NOT IN |
|---|---|---|---|---|---|---|---|---|---|
Yes | Yes | No | No | No | No | No | No | Yes | Yes |
None
Find only personal spaces
1 2space.type = personal
Find only site / global spaces
1 2space.type = global
Find only site / favorite spaces
1 2space.type = favorite
This is a "master-field" that allows you to search for text across a number of other text fields. These are the same fields used by Confluence search user interface.
Note: Confluence text-search syntax can be used with this field.
1 2text
TEXT
= | != | ~ | !~ | > | >= | < | <= | IN | NOT IN |
|---|---|---|---|---|---|---|---|---|---|
No | No | Yes | Yes | No | No | No | No | No | No |
none
Find content that contains the word Confluence.
1 2text ~ Confluence
Find content in the development space.
1 2space = DEV
Search for content by title, or with a title that contains particular text.
Note: Confluence text-search syntax can be used with this fields when used with the CONTAINS operator ("", "!")
1 2title
TEXT
= | != | ~ | !~ | > | >= | < | <= | IN | NOT IN |
|---|---|---|---|---|---|---|---|---|---|
Yes | Yes | Yes | Yes | No | No | No | No | Yes | Yes |
none
Find content with the title "Advanced Searching using CQL".
1 2title = "Advanced Searching using CQL"
Find content that matches Searching CQL (i.e. a "fuzzy" match).
1 2title ~ "Searching CQL"
Search for content of a particular type. Supported content types are:
1 2type
TYPE
= | != | ~ | !~ | > | >= | < | <= | IN | NOT IN |
|---|---|---|---|---|---|---|---|---|---|
Yes | Yes | No | No | No | No | No | No | Yes | Yes |
none
Find blogposts or pages
1 2type IN (blogpost, page)
Find attachments
1 2type = attachment
Search for content that a particular user is watching. You can search by the user's username.
1 2watcher
USER
= | != | ~ | !~ | > | >= | < | <= | IN | NOT IN |
|---|---|---|---|---|---|---|---|---|---|
Yes | Yes | No | No | No | No | No | No | Yes | Yes |
Search for content that you are watching.
1 2watcher = currentUser()
Search for content that the user "jsmith" is watching.
1 2watcher = "jsmith"
aliases:
This page contains examples of using the Confluence Content REST API using curl. The responses are piped into python -mjson.tool JSON encoder / decoder to make them easier to read.
Because the REST API is based on open standards, you can use any web development language to access the API.
These examples use basic authentication with a username and password. You can also create a personal access token for authentication (Confluence 7.9 and later).
This example shows how you can browse content. If you're using Confluence 7.18 or later, there's a more performant option that might be useful below.
1 2curl -u admin:admin http://localhost:8080/confluence/rest/api/content?limit=2 | python -mjson.tool
Example result:
1 2{ "results": [ { "id": "393219", "type": "page", "status": "current", "title": "First space", "extensions": { "position": 0 }, "_links": { "webui": "/display/FS/First+space", "edit": "/pages/resumedraft.action?draftId=393219", "tinyui": "/x/AwAG", "self": "http://localhost:8080/confluence/rest/api/content/393219" }, "_expandable": { "container": "/rest/api/space/FS", "metadata": "", "operations": "", "children": "/rest/api/content/393219/child", "restrictions": "/rest/api/content/393219/restriction/byOperation", "history": "/rest/api/content/393219/history", "ancestors": "", "body": "", "version": "", "descendants": "/rest/api/content/393219/descendant", "space": "/rest/api/space/FS" } }, { "id": "393229", "type": "page", "status": "current", "title": "Page 1", "extensions": { "position": 0 }, "_links": { "webui": "/display/FS/Page+1", "edit": "/pages/resumedraft.action?draftId=393229&draftShareId=f16d9e64-9373-4719-9df5-aec8102e5252", "tinyui": "/x/DQAG", "self": "http://localhost:8080/confluence/rest/api/content/393229" }, "_expandable": { "container": "/rest/api/space/FS", "metadata": "", "operations": "", "children": "/rest/api/content/393229/child", "restrictions": "/rest/api/content/393229/restriction/byOperation", "history": "/rest/api/content/393229/history", "ancestors": "", "body": "", "version": "", "descendants": "/rest/api/content/393229/descendant", "space": "/rest/api/space/FS" } } ], "start": 0, "limit": 2, "size": 2, "_links": { "self": "http://localhost:8080/confluence/rest/api/content", "next": "/rest/api/content?limit=2&start=2", "base": "http://localhost:8080/confluence", "context": "/confluence" } }
This example shows how you can browse content in Confluence 7.18 and later. The scan endpoint provides better performance, but can only be used to browse pages (not blogs), and doesn't support offset, title, or creationdate parameters.
1 2curl -u admin:admin http://localhost:8080/confluence/rest/api/content/scan?limit=2 | python -mjson.tool
Example result:
1 2{ "results": [ { "id": "393219", "type": "page", "status": "current", "title": "First space", "extensions": { "position": 0 }, "_links": { "webui": "/display/FS/First+space", "edit": "/pages/resumedraft.action?draftId=393219", "tinyui": "/x/AwAG", "self": "http://localhost:8080/confluence/rest/api/content/393219" }, "_expandable": { "container": "/rest/api/space/FS", "metadata": "", "operations": "", "children": "/rest/api/content/393219/child", "restrictions": "/rest/api/content/393219/restriction/byOperation", "history": "/rest/api/content/393219/history", "ancestors": "", "body": "", "version": "", "descendants": "/rest/api/content/393219/descendant", "space": "/rest/api/space/FS" } }, { "id": "393229", "type": "page", "status": "current", "title": "Page 1", "extensions": { "position": 0 }, "_links": { "webui": "/display/FS/Page+1", "edit": "/pages/resumedraft.action?draftId=393229&draftShareId=f16d9e64-9373-4719-9df5-aec8102e5252", "tinyui": "/x/DQAG", "self": "http://localhost:8080/confluence/rest/api/content/393229" }, "_expandable": { "container": "/rest/api/space/FS", "metadata": "", "operations": "", "children": "/rest/api/content/393229/child", "restrictions": "/rest/api/content/393229/restriction/byOperation", "history": "/rest/api/content/393229/history", "ancestors": "", "body": "", "version": "", "descendants": "/rest/api/content/393229/descendant", "space": "/rest/api/space/FS" } } ], "cursor": "content:false:null", "nextCursor": "content:false:393229", "limit": 2, "size": 2, "_links": { "self": "http://localhost:8080/confluence/rest/api/content/scan", "next": "/rest/api/content/scan?cursor=content:false:393229&limit=2", "base": "http://localhost:8080/confluence", "context": "/confluence" } }
To browse content with next or previous pagination use _links.next or _links.prev.
1 2curl -u admin:admin http://localhost:8080/confluence/rest/api/content?limit=2&start=2 | python -mjson.tool
Example result:
1 2{ "results": [ { "id": "393239", "type": "page", "status": "current", "title": "Page 3", "extensions": { "position": 2 }, "_links": { "webui": "/display/FS/Page+3", "edit": "/pages/resumedraft.action?draftId=393239&draftShareId=9041c7ee-064e-448e-a354-d2117661ec0c", "tinyui": "/x/FwAG", "self": "http://localhost:8080/confluence/rest/api/content/393239" }, "_expandable": { "container": "/rest/api/space/FS", "metadata": "", "operations": "", "children": "/rest/api/content/393239/child", "restrictions": "/rest/api/content/393239/restriction/byOperation", "history": "/rest/api/content/393239/history", "ancestors": "", "body": "", "version": "", "descendants": "/rest/api/content/393239/descendant", "space": "/rest/api/space/FS" } }, { "id": "393244", "type": "page", "status": "current", "title": "Second space Home", "extensions": { "position": "none" }, "_links": { "webui": "/display/SS/Second+space+Home", "edit": "/pages/resumedraft.action?draftId=393244", "tinyui": "/x/HAAG", "self": "http://localhost:8080/confluence/rest/api/content/393244" }, "_expandable": { "container": "/rest/api/space/SS", "metadata": "", "operations": "", "children": "/rest/api/content/393244/child", "restrictions": "/rest/api/content/393244/restriction/byOperation", "history": "/rest/api/content/393244/history", "ancestors": "", "body": "", "version": "", "descendants": "/rest/api/content/393244/descendant", "space": "/rest/api/space/SS" } } ], "start": 2, "limit": 2, "size": 2, "_links": { "self": "http://localhost:8080/confluence/rest/api/content", "next": "/rest/api/content?limit=2&start=4", "prev": "/rest/api/content?limit=2&start=0", "base": "http://localhost:8080/confluence", "context": "/confluence" } }
This example shows how you can browse content with pagination in Confluence 7.18 and later. The scan endpoint provides better performance, but can only be used to browse pages (not blogs), and doesn't support offset, title, or creationdate parameters.
To browse content with next or previous pagination you can still use _links.next or _links.prev, or you can use the value of nextCursor and prevCursor to set the cursor in the next request.
To navigate forward using the value of nextCursor from the previous example:
1 2curl -u admin:admin http://localhost:8080/confluence/rest/api/content/scan?cursor=content:false:393229&limit=2 | python -mjson.tool
Example result:
1 2{ "results": [ { "id": "393239", "type": "page", "status": "current", "title": "Page 3", "extensions": { "position": 2 }, "_links": { "webui": "/display/FS/Page+3", "edit": "/pages/resumedraft.action?draftId=393239&draftShareId=9041c7ee-064e-448e-a354-d2117661ec0c", "tinyui": "/x/FwAG", "self": "http://localhost:8080/confluence/rest/api/content/393239" }, "_expandable": { "container": "/rest/api/space/FS", "metadata": "", "operations": "", "children": "/rest/api/content/393239/child", "restrictions": "/rest/api/content/393239/restriction/byOperation", "history": "/rest/api/content/393239/history", "ancestors": "", "body": "", "version": "", "descendants": "/rest/api/content/393239/descendant", "space": "/rest/api/space/FS" } }, { "id": "393244", "type": "page", "status": "current", "title": "Second space Home", "extensions": { "position": "none" }, "_links": { "webui": "/display/SS/Second+space+Home", "edit": "/pages/resumedraft.action?draftId=393244", "tinyui": "/x/HAAG", "self": "http://localhost:8080/confluence/rest/api/content/393244" }, "_expandable": { "container": "/rest/api/space/SS", "metadata": "", "operations": "", "children": "/rest/api/content/393244/child", "restrictions": "/rest/api/content/393244/restriction/byOperation", "history": "/rest/api/content/393244/history", "ancestors": "", "body": "", "version": "", "descendants": "/rest/api/content/393244/descendant", "space": "/rest/api/space/SS" } } ], "cursor": "content:false:393229", "nextCursor": "content:false:393244", "prevCursor": "content:true:393239", "limit": 2, "size": 2, "_links": { "self": "http://localhost:8080/confluence/rest/api/content/scan?cursor=content:false:393229", "next": "/rest/api/content/scan?cursor=content:false:393244&limit=2", "prev": "/rest/api/content/scan?cursor=content:true:393239&limit=2", "base": "http://localhost:8080/confluence", "context": "/confluence" } }
This example shows how you can read content of a page with the body expanded.
1 2curl -u admin:admin http://localhost:8080/confluence/rest/api/content/3965072?expand=body.storage | python -mjson.tool
Example result:
1 2{ "_expandable": { "ancestors": "", "children": "", "container": "", "history": "/rest/api/content/3965072/history", "metadata": "", "space": "/rest/api/space/TST", "version": "" }, "_links": { "base": "http://localhost:8080/confluence", "collection": "/rest/api/contents", "self": "http://localhost:8080/confluence/rest/api/content/3965072", "tinyui": "/x/kIA8", "webui": "/display/TST/Test+Page" }, "body": { "editor": { "_expandable": { "content": "/rest/api/content/3965072" }, "representation": "editor" }, "export_view": { "_expandable": { "content": "/rest/api/content/3965072" }, "representation": "export_view" }, "storage": { "_expandable": { "content": "/rest/api/content/3965072" }, "representation": "storage", "value": "<p>blah blah</p>" }, "view": { "_expandable": { "content": "/rest/api/content/3965072" }, "representation": "view" } }, "id": "3965072", "title": "Test Page", "type": "page" }
This example shows how you can find pages in Confluence 7.18 and later. The scan endpoint provides better performance, but can only be used to browse pages (not blogs), and doesn't support offset, title, or creationdate parameters.
This example shows how you can find a page by space key, with history expanded to find the creator.
1 2curl -u admin:admin http://localhost:8080/confluence/rest/api/content/scan?spaceKey=FS&limit=2&expand=history | python -mjson.tool
Example result:
1 2{ "results": [ { "id": "393219", "type": "page", "status": "current", "title": "First space", "history": { "latest": true, "createdBy": { "type": "anonymous", "profilePicture": { "path": "/confluence/s/-ze4av5/8804/0/_/images/icons/profilepics/anonymous.svg", "width": 48, "height": 48, "isDefault": true }, "displayName": "Anonymous" }, "createdDate": "2022-04-27T07:15:13.012+10:00", "_links": { "self": "http://localhost:8080/confluence/rest/api/content/393219/history" }, "_expandable": { "lastUpdated": "", "previousVersion": "", "contributors": "", "nextVersion": "" } }, "extensions": { "position": 0 }, "_links": { "webui": "/display/FS/First+space", "edit": "/pages/resumedraft.action?draftId=393219", "tinyui": "/x/AwAG", "self": "http://localhost:8080/confluence/rest/api/content/393219" }, "_expandable": { "container": "/rest/api/space/FS", "metadata": "", "operations": "", "children": "/rest/api/content/393219/child", "restrictions": "/rest/api/content/393219/restriction/byOperation", "ancestors": "", "body": "", "version": "", "descendants": "/rest/api/content/393219/descendant", "space": "/rest/api/space/FS" } }, { "id": "393229", "type": "page", "status": "current", "title": "Page 1", "history": { "latest": true, "createdBy": { "type": "known", "username": "admin", "userKey": "2c9d802a8067b72f018067b876420000", "profilePicture": { "path": "/confluence/images/icons/profilepics/default.svg", "width": 48, "height": 48, "isDefault": true }, "displayName": "admin", "_links": { "self": "http://localhost:8080/confluence/rest/api/user?key=2c9d802a8067b72f018067b876420000" }, "_expandable": { "status": "" } }, "createdDate": "2022-04-27T07:15:18.097+10:00", "_links": { "self": "http://localhost:8080/confluence/rest/api/content/393229/history" }, "_expandable": { "lastUpdated": "", "previousVersion": "", "contributors": "", "nextVersion": "" } }, "extensions": { "position": 0 }, "_links": { "webui": "/display/FS/Page+1", "edit": "/pages/resumedraft.action?draftId=393229&draftShareId=f16d9e64-9373-4719-9df5-aec8102e5252", "tinyui": "/x/DQAG", "self": "http://localhost:8080/confluence/rest/api/content/393229" }, "_expandable": { "container": "/rest/api/space/FS", "metadata": "", "operations": "", "children": "/rest/api/content/393229/child", "restrictions": "/rest/api/content/393229/restriction/byOperation", "ancestors": "", "body": "", "version": "", "descendants": "/rest/api/content/393229/descendant", "space": "/rest/api/space/FS" } } ], "cursor": "content:false:null", "nextCursor": "content:false:393229", "limit": 2, "size": 2, "_links": { "self": "http://localhost:8080/confluence/rest/api/content/scan?spaceKey=FS&expand=history", "next": "/rest/api/content/scan?spaceKey=FS&cursor=content:false:393229&expand=history&limit=2", "base": "http://localhost:8080/confluence", "context": "/confluence" } }
This example shows how you can find a page by space key and title with history expanded to find the creator.
1 2curl -u admin:admin -X GET "http://localhost:8080/confluence/rest/api/content?title=myPage%20Title &spaceKey=TST&expand=history" | python -mjson.tool
Example result:
1 2{ "_links": { "self": "http://localhost:8080/confluence/rest/api/content" }, "limit": 100, "results": [ { "_expandable": { "ancestors": "", "body": "", "children": "/rest/api/content/950276/child", "container": "", "descendants": "/rest/api/content/950276/descendant", "metadata": "", "space": "/rest/api/space/TST", "version": "" }, "_links": { "self": "http://localhost:8080/confluence/rest/api/content/950276", "tinyui": "/x/BIAO", "webui": "/display/TST/myPage+Title" }, "history": { "_expandable": { "lastUpdated": "" }, "_links": { "self": "http://localhost:8080/confluence/rest/api/content/950276/history" }, "createdBy": { "displayName": "A. D. Ministrator", "profilePicture": { "height": 48, "isDefault": true, "path": "/confluence/s/en_GB-1988229788/4960/NOCACHE1/_/images/icons/profilepics/default.png", "width": 48 }, "type": "known", "username": "admin" }, "createdDate": "2014-03-07T17:08:20.326+1100", "latest": true }, "id": "950276", "title": "myPage Title", "type": "page" } ], "size": 1, "start": 0 }
This example finds blog posts to display in a blog roll with labels.
1 2curl -u admin:admin -X GET "http://localhost:8080/confluence/rest/api/content?type=blogpost&start=0 &limit=10&expand=space,history,body.view,metadata.labels" | python -mjson.tool
Example result:
1 2{ "_links": { "self": "http://localhost:8080/confluence/rest/api/content" }, "limit": 10, "results": [ { "_expandable": { "ancestors": "", "children": "/rest/api/content/557065/child", "container": "", "descendants": "/rest/api/content/557065/descendant", "version": "" }, "_links": { "self": "http://localhost:8080/confluence/rest/api/content/557065", "tinyui": "/x/CYAI", "webui": "/display/TST/Test+Space+Home" }, "body": { "editor": { "_expandable": { "content": "/rest/api/content/557065" }, "representation": "editor" }, "export_view": { "_expandable": { "content": "/rest/api/content/557065" }, "representation": "export_view" }, "storage": { "_expandable": { "content": "/rest/api/content/557065" }, "representation": "storage" }, "view": { "_expandable": { "content": "/rest/api/content/557065" }, "representation": "view", "value": "<p>Example page</p>" } }, "history": { "_expandable": { "lastUpdated": "" }, "_links": { "self": "http://localhost:8080/confluence/rest/api/content/557065/history" }, "createdBy": { "displayName": "A. D. Ministrator", "profilePicture": { "height": 48, "isDefault": true, "path": "/confluence/s/en_GB-1988229788/4960/NOCACHE1/_/images/icons/profilepics/default.png", "width": 48 }, "type": "known", "username": "admin" }, "createdDate": "2014-03-07T16:14:35.220+1100", "latest": true }, "id": "557065", "metadata": { "labels": { "_links": { "self": "http://localhost:8080/confluence/rest/api/content/557065/label" }, "limit": 200, "results": [], "size": 0, "start": 0 }, "reactionsCount": null }, "space": { "_links": { "self": "http://localhost:8080/confluence/rest/api/space/TST" }, "id": 786433, "key": "TST", "name": "Test Space" }, "title": "Test Space Home", "type": "page" }, { "_expandable": { "ancestors": "", "children": "/rest/api/content/557067/child", "container": "", "descendants": "/rest/api/content/557067/descendant", "version": "" }, "_links": { "self": "http://localhost:8080/confluence/rest/api/content/557067", "tinyui": "/x/C4AI", "webui": "/display/TST/A+new+page" }, "body": { "editor": { "_expandable": { "content": "/rest/api/content/557067" }, "representation": "editor" }, "export_view": { "_expandable": { "content": "/rest/api/content/557067" }, "representation": "export_view" }, "storage": { "_expandable": { "content": "/rest/api/content/557067" }, "representation": "storage" }, "view": { "_expandable": { "content": "/rest/api/content/557067" }, "representation": "view", "value": "" } }, "history": { "_expandable": { "lastUpdated": "" }, "_links": { "self": "http://localhost:8080/confluence/rest/api/content/557067/history" }, "createdBy": { "displayName": "A. D. Ministrator", "profilePicture": { "height": 48, "isDefault": true, "path": "/confluence/s/en_GB-1988229788/4960/NOCACHE1/_/images/icons/profilepics/default.png", "width": 48 }, "type": "known", "username": "admin" }, "createdDate": "2014-03-07T16:18:33.554+1100", "latest": true }, "id": "557067", "metadata": { "labels": { "_links": { "self": "http://localhost:8080/confluence/rest/api/content/557067/label" }, "limit": 200, "results": [], "size": 0, "start": 0 }, "reactionsCount": null }, "space": { "_links": { "self": "http://localhost:8080/confluence/rest/api/space/TST" }, "id": 786433, "key": "TST", "name": "Test Space" }, "title": "A new page", "type": "page" }, { "_expandable": { "ancestors": "", "children": "/rest/api/content/950276/child", "container": "", "descendants": "/rest/api/content/950276/descendant", "version": "" }, "_links": { "self": "http://localhost:8080/confluence/rest/api/content/950276", "tinyui": "/x/BIAO", "webui": "/display/TST/myPage+Title" }, "body": { "editor": { "_expandable": { "content": "/rest/api/content/950276" }, "representation": "editor" }, "export_view": { "_expandable": { "content": "/rest/api/content/950276" }, "representation": "export_view" }, "storage": { "_expandable": { "content": "/rest/api/content/950276" }, "representation": "storage" }, "view": { "_expandable": { "content": "/rest/api/content/950276" }, "representation": "view", "value": "<p>Some content</p>" } }, "history": { "_expandable": { "lastUpdated": "" }, "_links": { "self": "http://localhost:8080/confluence/rest/api/content/950276/history" }, "createdBy": { "displayName": "A. D. Ministrator", "profilePicture": { "height": 48, "isDefault": true, "path": "/confluence/s/en_GB-1988229788/4960/NOCACHE1/_/images/icons/profilepics/default.png", "width": 48 }, "type": "known", "username": "admin" }, "createdDate": "2014-03-07T17:08:20.326+1100", "latest": true }, "id": "950276", "metadata": { "labels": { "_links": { "self": "http://localhost:8080/confluence/rest/api/content/950276/label" }, "limit": 200, "results": [], "size": 0, "start": 0 }, "reactionsCount": null }, "space": { "_links": { "self": "http://localhost:8080/confluence/rest/api/space/TST" }, "id": 786433, "key": "TST", "name": "Test Space" }, "title": "myPage Title", "type": "page" } ], "size": 3, "start": 0 }
This example shows how you can create a new page with content in a specific space.
1 2curl -u admin:admin -X POST -H 'Content-Type: application/json' -d '{"type":"page","title":"new page", "space":{"key":"TST"},"body":{"storage":{"value":"<p>This is <br/> a new page</p>","representation": "storage"}}}' http://localhost:8080/confluence/rest/api/content/ | python -mjson.tool
Example result:
1 2{ "_expandable": { "children": "/rest/api/content/3604482/child", "descendants": "/rest/api/content/3604482/descendant", "metadata": "" }, "_links": { "base": "http://localhost:8080/confluence", "collection": "/rest/api/contents", "self": "http://localhost:8080/confluence/rest/api/content/3604482", "tinyui": "/x/AgA3", "webui": "/display/TST/new+page" }, "ancestors": [], "body": { "editor": { "_expandable": { "content": "/rest/api/content/3604482" }, "representation": "editor" }, "export_view": { "_expandable": { "content": "/rest/api/content/3604482" }, "representation": "export_view" }, "storage": { "_expandable": { "content": "/rest/api/content/3604482" }, "representation": "storage", "value": "<p>This is a new page</p>" }, "view": { "_expandable": { "content": "/rest/api/content/3604482" }, "representation": "view" } }, "container": { "_links": { "self": "http://localhost:8080/confluence/rest/api/space/TST" }, "id": 2719747, "key": "TST", "name": "Test Space" }, "history": { "_expandable": { "lastUpdated": "" }, "_links": { "self": "http://localhost:8080/confluence/rest/api/content/3604482/history" }, "createdBy": { "displayName": "A. D. Ministrator", "profilePicture": { "height": 48, "isDefault": true, "path": "/confluence/s/en_GB-1988229788/4960/NOCACHE1/_/images/icons/profilepics/default.png", "width": 48 }, "type": "known", "username": "admin" }, "createdDate": "2014-03-10T23:14:35.031+1100", "latest": true }, "id": "3604482", "space": { "_links": { "self": "http://localhost:8080/confluence/rest/api/space/TST" }, "id": 2719747, "key": "TST", "name": "Test Space" }, "title": "new page", "type": "page", "version": { "by": { "displayName": "A. D. Ministrator", "profilePicture": { "height": 48, "isDefault": true, "path": "/confluence/s/en_GB-1988229788/4960/NOCACHE1/_/images/icons/profilepics/default.png", "width": 48 }, "type": "known", "username": "admin" }, "message": "", "minorEdit": false, "number": 1, "when": "2014-03-10T23:14:35.031+1100" } }
1 2//This creates a page in a space. var username = "admin"; var password = "admin"; var jsondata = {"type":"page", "title":"My Test Page", "space":{"key":"TST"}, "body":{"storage":{"value":"<p>This is a new page</p>","representation":"storage"}}}; $.ajax ({ type: "POST", url: "http://localhost:8080/confluence/rest/api/content/", contentType:"application/json; charset=utf-8", dataType: "json", async: false, headers: { "Authorization": "Basic " + btoa(username+ ":" + password) }, data: JSON.stringify(jsondata), success: function (){ console.log('Page saved!'); }, error : function(xhr, errorText){ console.log('Error '+ xhr.responseText); } });
This example shows how you can create a new page, with content, as a child of another page with ID 456
1 2curl -u admin:admin -X POST -H 'Content-Type: application/json' -d '{"type":"page","title":"new page", "ancestors":[{"id":456}], "space":{"key":"TST"},"body":{"storage":{"value": "<p>This is a new page</p>","representation":"storage"}}}' http://localhost:8080/confluence/rest/api/content/ | python -mjson.tool
This example shows how you can update the content of an existing page.
1 2curl -u admin:admin -X PUT -H 'Content-Type: application/json' -d '{"id":"3604482","type":"page", "title":"new page","space":{"key":"TST"},"body":{"storage":{"value": "<p>This is the updated text for the new page</p>","representation":"storage"}}, "version":{"number":2}}' http://localhost:8080/confluence/rest/api/content/3604482 | python -mjson.tool
Example result:
1 2{ "_expandable": { "children": "/rest/api/content/3604482/child", "descendants": "/rest/api/content/3604482/descendant", "metadata": "" }, "_links": { "base": "http://localhost:8080/confluence", "collection": "/rest/api/contents", "self": "http://localhost:8080/confluence/rest/api/content/3604482", "tinyui": "/x/AgA3", "webui": "/display/TST/new+page" }, "ancestors": [], "body": { "editor": { "_expandable": { "content": "/rest/api/content/3604482" }, "representation": "editor" }, "export_view": { "_expandable": { "content": "/rest/api/content/3604482" }, "representation": "export_view" }, "storage": { "_expandable": { "content": "/rest/api/content/3604482" }, "representation": "storage", "value": "<p>This is the updated text for the new page</p>" }, "view": { "_expandable": { "content": "/rest/api/content/3604482" }, "representation": "view" } }, "container": { "_links": { "self": "http://localhost:8080/confluence/rest/api/space/TST" }, "id": 2719747, "key": "TST", "name": "Test Space" }, "history": { "_expandable": { "lastUpdated": "", "previousVersion": "" }, "_links": { "self": "http://localhost:8080/confluence/rest/api/content/3604482/history" }, "createdBy": { "displayName": "A. D. Ministrator", "profilePicture": { "height": 48, "isDefault": true, "path": "/confluence/s/en_GB-1988229788/4960/NOCACHE1/_/images/icons/profilepics/default.png", "width": 48 }, "type": "known", "username": "admin" }, "createdDate": "2014-03-10T23:14:35.031+1100", "latest": true }, "id": "3604482", "space": { "_links": { "self": "http://localhost:8080/confluence/rest/api/space/TST" }, "id": 2719747, "key": "TST", "name": "Test Space" }, "title": "new page", "type": "page", "version": { "by": { "displayName": "A. D. Ministrator", "profilePicture": { "height": 48, "isDefault": true, "path": "/confluence/s/en_GB-1988229788/4960/NOCACHE1/_/images/icons/profilepics/default.png", "width": 48 }, "type": "known", "username": "admin" }, "minorEdit": false, "number": 2, "when": "2014-03-10T23:16:50.757+1100" } }
This example shows how you can delete a page by content ID.
1 2curl -v -S -u admin:admin -X DELETE http://localhost:8080/confluence/rest/api/content/3604482 | python -mjson.tool
Expect a HTTP/1.1 204 No Content response after a successful deletion.
This example shows how you can upload an attachment to a specific page (where 3604482 is the content ID), and add a comment.
1 2curl -v -S -u admin:admin -X POST -H "X-Atlassian-Token: no-check" -F "file=@myfile.txt" -F "comment=this is my file" "http://localhost:8080/confluence/rest/api/content/3604482/child/attachment" | python -mjson.tool
1 2{ "_expandable": { "icon": "" }, "_links": { "base": "http://localhost:8080/confluence", "collection": "/rest/api/space", "context": "/confluence", "self": "http://localhost:8080/confluence/rest/api/space/RAID4" }, "description": { "_expandable": { "view": "" }, "plain": { "representation": "plain", "value": "Raider Space for raiders" } }, "homepage": { "_expandable": { "ancestors": "", "body": "", "children": "/rest/api/content/3997704/child", "container": "", "descendants": "/rest/api/content/3997704/descendant", "history": "/rest/api/content/3997704/history", "metadata": "", "space": "/rest/api/space/RAID4", "version": "" }, "_links": { "self": "http://localhost:8080/confluence/rest/api/content/3997704", "tinyui": "/x/CAA9", "webui": "/display/RAID4/Raider+Home" }, "id": "3997704", "title": "Raider Home", "type": "page" }, "id": 4030468, "key": "RAID", "name": "Raider", "type": "global" }
This example shows how you can download an attachment from a specific page (where 1998856 is the content ID).
1 2curl -u admin:admin "http://localhost:8080/confluence/rest/api/content/1998856/child/attachment" | python -m json.tool
The download link is inside output:
1 2"_links": { "download": "/download/attachments/1998856/test.txt?version=1&modificationDate=1519985997040&api=v2", "self": "http://localhost:8080/confluence/rest/api/content/att1998865", "webui":"/display/dsada/new4+page?preview=%2F1998856%2F1998865%2Ftest.txt" }
1 2curl -u admin:admin "http://localhost:8080/confluence/rest/api/content/1998856/child/comment?expand=body.view&depth=all" | python -m json.tool
1 2{ "_links": { "base": "http://localhost:8080/confluence", "context": "/confluence", "self": "http://localhost:8080/confluence/rest/api/content/1998856/child/comment?expand=body.view" }, "limit": 25, "results": [ { "_expandable": { "ancestors": "", "children": "/rest/api/content/1998866/child", "container": "/rest/api/content/1998856", "descendants": "/rest/api/content/1998866/descendant", "history": "/rest/api/content/1998866/history", "metadata": "", "operations": "", "restrictions": "/rest/api/content/1998866/restriction/byOperation", "space": "/rest/api/space/dsada", "version": "" }, "_links": { "self": "http://localhost:8080/confluence/rest/api/content/1998866", "webui": "/display/dsada/new4+page?focusedCommentId=1998866#comment-1998866" }, "body": { "_expandable": { "anonymous_export_view": "", "editor": "", "export_view": "", "storage": "", "styled_view": "" }, "view": { "_expandable": { "content": "/rest/api/content/1998866", "webresource": "" }, "representation": "storage", "value": "<p><strong>I am a comment</strong></p>" } }, "extensions": { "_expandable": { "resolution": "" }, "location": "footer" }, "id": "1998866", "status": "current", "title": "Re: new4 page", "type": "comment" } ], "size": 1, "start": 0 }
This Python example shows how you can add a comment to a page. First, the page for commenting is fetched from API by title, and then used as the container of the comment.
comment.py
1 2import requests, json def printResponse(r): print '{} {}\n'.format(json.dumps(r.json(), sort_keys=True, indent=4, separators=(',', ': ')), r) r = requests.get('http://localhost:8080/confluence/rest/api/content', params={'title' : 'Page title to comment on'}, auth=('admin', 'admin')) printResponse(r) parentPage = r.json()['results'][0] pageData = {'type':'comment', 'container':parentPage, 'body':{'storage':{'value':"<p>A new comment</p>",'representation':'storage'}}} r = requests.post('http://localhost:8080/confluence/rest/api/content', data=json.dumps(pageData), auth=('admin','admin'), headers=({'Content-Type':'application/json'})) printResponse(r)
This examples is similar to creating a page but you need to use the following JSON body, see Confluence Storage Format documenation for other storage format markup that you can use.
1 2POST /rest/api/content : { "type":"page", "title":"Another planning specs with username", "body":{ "storage":{"value": "<ac:task-list> <ac:task> <ac:task-status>incomplete</ac:task-status> <ac:task-body> <ac:link><ri:user ri:username='admin' /></ac:link> do something </ac:task-body> </ac:task> </ac:task-list>", "representation":"storage"}}, "space":{"key":"TST"} }
This example shows how you can create a new space.
1 2curl -u admin:admin -X POST -H 'Content-Type: application/json' -d' { "key":"RAID", "name":"Raider", "type":"global", "description":{"plain": { "value": "Raider Space for raiders","representation": "plain" }}}' http://localhost:8080/confluence/rest/api/space
This example shows how to convert storage format to view format.
1 2curl -u admin:admin -X POST -H 'Content-Type: application/json' -d'{"value":"<ac:structured-macro ac:name=\"cheese\" />","representation":"storage"}' "http://localhost:8080/confluence/rest/api/contentbody/convert/view" | python -mjson.tool
Example result:
1 2{ "_links": { "base": "http://localhost:8080/confluence" }, "representation": "view", "value": "I like cheese!" }
This example shows how to convert wiki markup to storage format.
1 2curl -u admin:admin -X POST -H 'Content-Type: application/json' -d'{"value":"{cheese}", "representation":"wiki"}' "http://localhost:8080/confluence/rest/api/contentbody/convert/storage" | python -mjson.tool
Example result:
1 2{ "_links": { "base": "http://localhost:8080/confluence" }, "representation": "storage", "value": "<ac:structured-macro ac:name=\"cheese\" />" }
This example also shows how to convert storage format to view format, but this time using an existing piece of content for the conversion context. Some macros require a page context when they are executed. I'm using the space attachments macro. To determine what attachments to show on the page, this macro uses the space that the page is in.
1 2curl -u admin:admin -X POST -H 'Content-Type: application/json' -d'{"representation":"storage", "value":"<p><ac:structured-macro ac:name=\"space-attachments\"/></p>","content":{"id":"1448805348"}}' "http://localhost:8080/confluence/rest/api/contentbody/convert/view" | python -mjson.tool
aliases:
Content properties are a form of key-value storage, where the key is associated with a piece of Confluence Content. Content properties are one of the forms of persistence available to you as an add-on developer. Content properties allow to store up to 32 KB of JSON with each piece of content (for example, a page, blog post, or attachment), so, you do not have to use your own data store. If you need to store metadata, for example, about a piece (or pieces) of content, content property is a great way to do it.
Content properties are accessible both by Java and REST APIs.
You can use CQL to query content properties in your Confluence instance. For example, a plugin can store the number of likes on a page in a content property. You can create an index schema module for that property, and then you can query the values to see how many pieces of content have more than 20 likes.
GET content properties
To retrieve any existing content properties for a piece of content, perform a GET on the
endpoint /rest/api/content/{content_ID}/property.
1 2# Retrieves content properties associated with a piece of content with ID 12345 curl -u admin:admin -X GET "http://localhost:8080/confluence/rest/api/content/12345/property" | python -mjson.tool
POST new content properties
To add content properties to a piece of Confluence content, perform a POST to the same endpoint. The key in your content property can be an arbitrary string (like "myprop"), whereas the value must be a structured JSON.
1 2# Stores a JSON document under the key "myprop" against content with ID 12345 curl -i -u admin:admin -X POST -H "Content-Type: application/json" \ -d '{ "key" : "myprop", "value" : { "id": "507f1f77bcf86cd799439011", "editDate": "2000-01-01T11:00:00.000+11:00", "description": "If you have any questions please address them to admin@example.com", "content": { "likes": 5, "tags": ["cql", "confluence"] } } }' http://localhost:8080/confluence/rest/api/content/12345/property
DELETE content properties
If you need to delete content properties, you can perform a DELETE on the endpoint.
1 2# Removes JSON document associated with key "myprop from content with ID 12345 curl -i -u admin:admin -X DELETE "http://localhost:8080/confluence/rest/api/content/12345/property/myprop"
Content properties are available as an expansion on the content resource. This allows content properties to be retrieved in the same REST call as fetching the content itself. This expansion is available from any resource that returns content, including the CQL search resource.
GET content properties as an expansion on content.
1 2# fetch properties at the same time as fetching content, note the expand=metadata.properties.myprop curl -u admin:admin -X GET "http://localhost:8080/confluence/rest/api/content/12345?expand=metadata.properties.myprop" | python -mjson.tool { id: "12345", type: "page", status: "current", title: "New in the platform team? Read me first", metadata: { _expandable: { currentuser: "", labels: "", properties: { myprop: { "id": "507f1f77bcf86cd799439011", "editDate": "2000-01-01T11:00:00.000+11:00", "description": "If you have any questions please address them to admin@example.com", "content": { "likes": 5, "tags": ["cql", "confluence"] } } } } } }
To allow searching of content properties using CQL, you can enable indexing of data stored as content properties by defining an index schema. You can define an exclusive index schema for each content property key; then, whenever a content property is saved, Confluence checks if a schema is defined for its key. If a schema exists, indexable values are extracted from content property values and stored in an index. There can only be one index schema definition for a content property key, so any duplicates are disabled. In the case of offending keys, an appropriate log message is available.
When defining an index schema for content properties, you need to provide a set of extraction expressions and field
type pairs, which are used to retrieve a specific value from a JSON document and transform it into the desired representation.
Supported index field types are: string, text, number, and date.
For an example, see the JSON document and its index schema later on this page.
Example of content property value.
1 2{ "id": "507f1f77bcf86cd799439011", "editDate": "2000-01-01T11:00:00.000+11:00", "description": "If you have any questions please address them to admin@example.com", "content": { "likes": 5, "tags": ["cql", "confluence"] } }
| Extraction definition for a P2 plugin | Extracted value |
|---|---|
<extract path="id" type="string" /> | "507f1f77bcf86cd799439011" |
<extract path="editDate" type="date" /> | 1st of Jan 2000 00:00:00.000 UTC |
<extract path="content.tags" type="string" /> | An array containing "cql", "confluence" |
<extract path="content.likes" type="number" /> | 5 |
To access an embedded field in a document, use dot notation as shown in the following example. After successful validation, all extracted values are stored inside an index, and you can address them in CQL queries.
Putting it all together, here's a sample index schema definition:
atlassian-plugin.xml
Example of P2 add-on index schema definition
1 2<content-property-index-schema key="module-key"> <key property-key="attachments"> <extract path="id" type="string" /> <extract path="description" type="text" /> <extract path="editDate" type="date" /> </key> <key property-key="metadata"> <extract path="content.tags" type="string" /> <extract path="content.likes" type="number" /> </key> </content-property-index-schema>
Field type doesn't only specify how data is stored in the index, but also determines which CQL operators are available in your query.
| Type | Description | Supported CQL operators |
|---|---|---|
string | Entire extracted value will be indexed as a single token, without any filtering. When extraction expression evaluates to a JSON array, each element will be indexed separately. Enables searching for an exact value, e.g. unique identifier. | IN, NOT IN, =, != |
text | Extracted value will be tokenized before indexing, allowing searching for a particular words. | ~, !~ |
number | Extracted number will be indexed as a double value for efficient range filtering. |
<, <=, =, !=, >, >=
|
date | Two representation are possible, either a String following the ISO 8601 datetime format, or a long value in the Unix time. Enables efficient range filtering.
| <, <=, =, !=, >, >=
|
You can't currently sort by these fields. See CONFSERVER-58077.
You can address indexed content properties in a CQL query using the content.property field handler.
Any content that contains content properties matching the query is returned in the results.
The query syntax is as follows: content.property[<KEY>].<PATH> <OPERATOR> value.
Examples of CQL queries on content properties.
1 2content.property[attachments].editDate >= 2001-01-01 content.property[attachments].description ~ "questions" content.property[metadata].content.tags IN ("cql", "help") content.property[metadata].content.likes <= 5
Note the dot notation when referencing embedded fields like 'content.likes'.
Legend
| Symbol | Meaning |
|---|---|
| KEY | The key of the content properties you search. |
| PATH | The path to the value you'd like to search in the JSON document (use dot notation for embedded fields). |
| OPERATOR | One of the supported CQL operators for the field type. |
Content properties which are attached to custom content can also be indexed in the content body field by defining search body property module descriptors which make reference to the custom content type and content property key. This makes custom content searchable by content properties via the CQL 'text' field and also the quick-nav search bar.
For the following examples assume we have two custom content types com.company.product.plugins.pluginName:customType and myCustomType with
defined content with IDs 123456789 and 987654321 respectively.
Examples of search body property definitions in atlassian-plugin.xml
1 2<search-body-property key="moduleKey" content-type="com.company.product.plugins.pluginName:customType" content-property="attachments" /> <search-body-property key="moduleKeyTwo" content-type="myCustomType" content-property="metadata" />
content-type refers to the custom content type.
content-property refers to the content property key to extract the value to be added to the content body field.
Examples of corresponding content properties POST requests for custom content
1 2# Stores a JSON document under the key "myprop" against content with ID 12345 curl -i -u admin:admin -X POST -H "Content-Type: application/json" \ -d '{ "key" : "attachments", "value" : "This text will be added to the content body field" }' http://localhost:8080/confluence/rest/api/content/123456789/property
1 2# Stores a JSON document under the key "myprop" against content with ID 12345 curl -i -u admin:admin -X POST -H "Content-Type: application/json" \ -d '{ "key" : "metadata", "value" : { "description": "The whole json value be added to the content body field", "content": { "likes": 5, "tags": ["cql", "confluence"] } } }' http://localhost:8080/confluence/rest/api/content/987654321/property
| Custom content type | Content id | What is added to content body field |
|---|---|---|
| com.company.product.plugins.pluginName:customType | 123456789 | "This text will be added to the content body field" |
| myCustomType | 987654321 | "{
"description": "The whole json value be added to the content body field",
"content": {
"likes": 5,
"tags": ["cql", "confluence"]
}
}" |
JSON expressions and extractions that are available when using the index schema are not available as part of the search body property descriptors. In the second content properties example above, the JSON inside the value field will be converted into text and stored in the content body field, even the JSON field names "description" and "content" will be used in indexing for search.
aliases:
The confluence-create-content-plugin provides an AbstractCreateBlueprintPageAction that you can extend to add custom behavior.
To use this module, make sure your pom.xml includes the following dependency:
1 2<dependency> <groupId>com.atlassian.confluence.plugins</groupId> <artifactId>confluence-create-content-plugin</artifactId> <version>${create-content.version}</version> <scope>provided</scope> </dependency>
The AbstractCreateBlueprintPageAction provides a couple of useful methods for working with blueprints:
populateBlueprintPage loads the blueprint content template and generates a blueprint page from the template and the context.getOrCreateIndexPage gets the index page for the blueprint or creates one if it doesn't exist, and pins it to the sidebar.For more details on how to write and link an action in Confluence, see Struts module.
Deprecation Warning:
The AbstractCreateBlueprintPageAction is no longer used internally and is slated for removal in a future release.
Please let us know via the feedback form if your plugin currently extends this action, or if you plan to extend it.
If you need to interact with the blueprints API at a low level, you can use BlueprintManager (see how to retrieve it).
It gives access to the following method.
| Method | |
|---|---|
createAndPinIndexPage | Creates an index page if required for this blueprint, and pins it to the Space Sidebar. |
If you need to interact with the blueprint configuration, you can use UserBlueprintConfigManager (see how to retrieve it).
It gives an access to the following method.
| Method | |
|---|---|
setBlueprintCreatedByUser | Flags that a Blueprint of a certain type has been created by a given user |
If you need to interact with the blueprint API at a low level, you can also use BlueprintContentGenerator (see how to retrieve it)
to get access to the render context. It gives an access to following methods.
| Component Key | Methods |
|---|---|
createIndexPageObject | Creates an index page object given a plugin template and a render context. |
| Creates an unsaved content page object for a create-Blueprint-page request. |
aliases:
To limit the number of calls to the API, and the size of the responses, Confluence REST API supports the expansion of certain elements. If your GET returns a list of results and you don't choose to expand anything, the response is short, displaying only a basic representation of the resource.
If you GET a specific piece of content – like a page by page ID (for example, http://localhost:8080/confluence/rest/api/content/12345,
where 12345 is the page ID) – Confluence expands some properties by default. For a specific page, it will expand the space,
history, and version information, but you can explicitly request expansion of different properties in your call.
In this example, we send a GET to return a list of pages in the space with the space key 'TEST':
1 2curl -u admin:admin -X GET "http://localhost:8080/confluence/rest/api/content?type=page&spaceKey=TEST" | python -mjson.tool
Notice that only id, status, title, and type are expanded, but the \_expandable block contains the properties that can be expanded.
1 2{ "_links": { "base": "http://localhost:8080/confluence", "context": "", "self": "http://localhost:8080/confluence/rest/api/content" }, "limit": 25, "results": [ { "_expandable": { "ancestors": "", "body": "", "children": "/rest/api/content/589828/child", "container": "", "descendants": "/rest/api/content/589828/descendant", "history": "/rest/api/content/589828/history", "metadata": "", "space": "/rest/api/space/TEST", "version": "" }, "_links": { "self": "http://localhost:8080/confluence/rest/api/content/589828", "tinyui": "/x/BAAJ", "webui": "/display/TEST/Test+Space+Home" }, "id": "589828", "status": "current", "title": "Test Space Home", "type": "page" } ], "size": 1, "start": 0 }
In the previous example, even though there's only one piece of content returned, nothing is expanded by default because we didn't request a specific piece of content. However, we get a list of expandable items.
As you know from the previous example, you can use the expand parameter to explicitly expand any or all of the following
items relating to the returned content item(s):
Rather than creating multiple calls to return the information you need, you can make one call and expand only the items you need.
If you need to expand more than one item, you can add them as a comma-separated list in the expand parameter. For example, if you need the history and version information for the resource(s), you can do the following:
1 2curl -u admin:admin -X GET "http://localhost:8080/confluence/rest/api/content?type=page&spaceKey=TEST&expand=history,version" | python -mjson.tool
Notice that version and history are expanded because we specify expand=history,version as a query parameter in the request.
1 2{ "_links": { "base": "http://localhost:8080/confluence", "context": "", "self": "http://localhost:8080/confluence/rest/api/content" }, "limit": 25, "results": [ { "_expandable": { "ancestors": "", "body": "", "children": "/rest/api/content/589828/child", "container": "", "descendants": "/rest/api/content/589828/descendant", "metadata": "", "space": "/rest/api/space/TEST" }, "_links": { "self": "http://localhost:8080/confluence/rest/api/content/589828", "tinyui": "/x/BAAJ", "webui": "/display/TEST/Test+Space+Home" }, "history": { "_expandable": { "lastUpdated": "", "nextVersion": "", "previousVersion": "" }, "_links": { "self": "http://localhost:8080/confluence/rest/api/content/589828/history" }, "createdBy": { "displayName": "Gil Admin", "profilePicture": { "height": 48, "isDefault": true, "path": "/s/en_GB/5723/dfa6f4056bde4993312ffa3cb0f626ca41e68821.1/_/images/icons/profilepics/default.png", "width": 48 }, "type": "known", "userKey": "2c968271494ecbb701494ecc80dd0002", "username": "admin" }, "createdDate": "2014-10-27T11:57:01.915+1100", "latest": true }, "id": "589828", "status": "current", "title": "Test Space Home", "type": "page", "version": { "by": { "displayName": "Gil Admin", "profilePicture": { "height": 48, "isDefault": true, "path": "/s/en_GB/5723/dfa6f4056bde4993312ffa3cb0f626ca41e68821.1/_/images/icons/profilepics/default.png", "width": 48 }, "type": "known", "userKey": "2c968271494ecbb701494ecc80dd0002", "username": "admin" }, "minorEdit": false, "number": 3, "when": "2014-10-27T14:17:30.558+1100" } } ], "size": 1, "start": 0 }
The response provides an expanded view of the page history and version information. Notice that
the expanded items can also contain nested items that can be further expanded. The history element also contains:
nextVersion, previousVersion, and lastUpdated, which can all be expanded in the response.
Apart from using a comma-separated list for expanding multiple elements, you can use dot-separated notation to expand nested elements.
For example, if you need only the history expanded, but you want to expand lastUpdated, call the following:
1 2curl -u admin:admin -X GET "http://localhost:8080/confluence/rest/api/content?type=page&spaceKey=TEST&expand=history.lastUpdated" | python -mjson.tool
Notice that the history object now includes the expanded lastUpdated object.
1 2{ "_links": { "base": "http://localhost:8080/confluence", "context": "", "self": "http://localhost:8080/confluence/rest/api/content" }, "limit": 25, "results": [ { "_expandable": { "ancestors": "", "body": "", "children": "/rest/api/content/589828/child", "container": "", "descendants": "/rest/api/content/589828/descendant", "metadata": "", "space": "/rest/api/space/TEST", "version": "" }, "_links": { "self": "http://localhost:8080/confluence/rest/api/content/589828", "tinyui": "/x/BAAJ", "webui": "/display/TEST/Test+Space+Home" }, "history": { "_expandable": { "nextVersion": "", "previousVersion": "" }, "_links": { "self": "http://localhost:8080/confluence/rest/api/content/589828/history" }, "createdBy": { "displayName": "Gil Admin", "profilePicture": { "height": 48, "isDefault": true, "path": "/s/en_GB/5723/dfa6f4056bde4993312ffa3cb0f626ca41e68821.1/_/images/icons/profilepics/default.png", "width": 48 }, "type": "known", "userKey": "2c968271494ecbb701494ecc80dd0002", "username": "admin" }, "createdDate": "2014-10-27T11:57:01.915+1100", "lastUpdated": { "by": { "displayName": "Gil Admin", "profilePicture": { "height": 48, "isDefault": true, "path": "/s/en_GB/5723/dfa6f4056bde4993312ffa3cb0f626ca41e68821.1/_/images/icons/profilepics/default.png", "width": 48 }, "type": "known", "userKey": "2c968271494ecbb701494ecc80dd0002", "username": "admin" }, "minorEdit": false, "number": 3, "when": "2014-10-27T14:17:30.558+1100" }, "latest": true }, "id": "589828", "status": "current", "title": "Test Space Home", "type": "page" } ], "size": 1, "start": 0 }
Another example is to expand the body of returned content in Confluence storage format (XHTML). If you GET the body in storage format, you can then PUT changes to that information to update the content.
We'll also expand the version in this call because we'll need to increment the version number when we PUT our changes.
1 2curl -u admin:admin -X GET "http://localhost:8080/confluence/rest/api/content?type=page&spaceKey=TEST&expand=body.storage,version" | python -mjson.tool
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66{ "_links": { "base": "http://localhost:8080/confluence", "context": "", "self": "http://localhost:8080/confluence/rest/api/content" }, "limit": 20, "results": [ { "_expandable": { "ancestors": "", "children": "/rest/api/content/589828/child", "container": "", "descendants": "/rest/api/content/589828/descendant", "history": "/rest/api/content/589828/history", "metadata": "", "space": "/rest/api/space/TEST" }, "_links": { "self": "http://localhost:8080/confluence/rest/api/content/589828", "tinyui": "/x/BAAJ", "webui": "/display/TEST/Test+Space+Home" }, "body": { "_expandable": { "anonymous_export_view": "", "editor": "", "export_view": "", "view": "" }, "storage": { "_expandable": { "content": "/rest/api/content/589828" }, "representation": "storage", "value": "<ac:layout><ac:layout-section ac:type=\"single\"><ac:layout-cell>\n<ac:structured-macro ac:name=\"tip\"><ac:parameter ac:name=\"title\">Welcome to my new space!</ac:parameter><ac:rich-text-body>\n <p>Confluence spaces are great for sharing content and news with your team. This is your home page. Right now it shows recent space activity, but you can customize this page in anyway you like.</p>\n </ac:rich-text-body></ac:structured-macro><h2>Complete these tasks to get started</h2><ac:task-list>\n<ac:task>\n<ac:task-id>1</ac:task-id>\n<ac:task-status>incomplete</ac:task-status>\n<ac:task-body>\n <strong>Edit this home page</strong> - Click <em>Edit</em> in the top right of this screen to customize your Space home page\n </ac:task-body>\n</ac:task>\n<ac:task>\n<ac:task-id>2</ac:task-id>\n<ac:task-status>incomplete</ac:task-status>\n<ac:task-body>\n <strong>Create your first page</strong> - Click the <em>Create</em> button in the header to get started\n </ac:task-body>\n</ac:task>\n<ac:task>\n<ac:task-id>3</ac:task-id>\n<ac:task-status>incomplete</ac:task-status>\n<ac:task-body>\n <strong>Brand your Space</strong> - Click <em>Configure Sidebar</em> in the left panel to update space details and logo\n </ac:task-body>\n</ac:task>\n<ac:task>\n<ac:task-id>4</ac:task-id>\n<ac:task-status>incomplete</ac:task-status>\n<ac:task-body>\n <strong>Set permissions</strong> - Click <em>Space Tools</em> in the left sidebar to update permissions and give others access\n </ac:task-body>\n</ac:task>\n</ac:task-list>\n\n<p> </p></ac:layout-cell></ac:layout-section><ac:layout-section ac:type=\"two_equal\"><ac:layout-cell>\n<h2>Recent space activity</h2><p>\n <ac:structured-macro ac:name=\"recently-updated\"><ac:parameter ac:name=\"hideHeading\">true</ac:parameter><ac:parameter ac:name=\"max\">5</ac:parameter><ac:parameter ac:name=\"theme\">social</ac:parameter><ac:parameter ac:name=\"types\">page, comment, blogpost</ac:parameter></ac:structured-macro>\n </p></ac:layout-cell><ac:layout-cell>\n<h2>Space contributors</h2><p>\n <ac:structured-macro ac:name=\"contributors\"><ac:parameter ac:name=\"limit\">5</ac:parameter><ac:parameter ac:name=\"scope\">descendants</ac:parameter><ac:parameter ac:name=\"order\">update</ac:parameter><ac:parameter ac:name=\"showLastTime\">true</ac:parameter><ac:parameter ac:name=\"mode\">list</ac:parameter></ac:structured-macro>\n </p></ac:layout-cell></ac:layout-section><ac:layout-section ac:type=\"single\"><ac:layout-cell>\n<p> </p></ac:layout-cell></ac:layout-section></ac:layout>" } }, "id": "589828", "status": "current", "title": "Test Space Home", "type": "page", "version": { "by": { "displayName": "Gil Admin", "profilePicture": { "height": 48, "isDefault": true, "path": "/s/en_GB/5723/dfa6f4056bde4993312ffa3cb0f626ca41e68821.1/_/images/icons/profilepics/default.png", "width": 48 }, "type": "known", "userKey": "2c968271494ecbb701494ecc80dd0002", "username": "admin" }, "message": "", "minorEdit": false, "number": 4, "when": "2014-10-27T16:09:24.368+1100" } } ], "size": 1, "start": 0 }
You can then PUT your changes as follows:
1 2curl -u admin:admin -X PUT -H 'Content-Type: application/json' -d'{"id":"589828","type":"page","title":"Test Space Home","space":{"key":"TEST"},"body":{"storage":{"value":"<p>This is the newly updated text for my page</p>","representation":"storage"}},"version":{"number":5}}' http://localhost:8080/confluence/rest/api/content/589828 | python -mjson.tool
Note that Confluence pages and blog posts are versioned, so you need to add the version number in your call.
1 2{ "_expandable": { "children": "/rest/api/content/589828/child", "descendants": "/rest/api/content/589828/descendant", "metadata": "" }, "_links": { "base": "http://localhost:8080/confluence", "collection": "/rest/api/content", "context": "", "self": "http://localhost:8080/confluence/rest/api/content/589828", "tinyui": "/x/BAAJ", "webui": "/display/TEST/Test+Space+Home" }, "ancestors": [], "body": { "_expandable": { "anonymous_export_view": "", "editor": "", "export_view": "", "view": "" }, "storage": { "_expandable": { "content": "/rest/api/content/589828" }, "representation": "storage", "value": "<p>This is the newly updated text for my page</p>" } }, "container": { "_expandable": { "description": "", "homepage": "/rest/api/content/589828", "icon": "" }, "_links": { "self": "http://localhost:8080/confluence/rest/api/space/TEST" }, "id": 753665, "key": "TEST", "name": "Test Space", "type": "global" }, "history": { "_expandable": { "lastUpdated": "", "nextVersion": "", "previousVersion": "" }, "_links": { "self": "http://localhost:8080/confluence/rest/api/content/589828/history" }, "createdBy": { "displayName": "Gil Admin", "profilePicture": { "height": 48, "isDefault": true, "path": "/s/en_GB/5723/dfa6f4056bde4993312ffa3cb0f626ca41e68821.1/_/images/icons/profilepics/default.png", "width": 48 }, "type": "known", "userKey": "2c968271494ecbb701494ecc80dd0002", "username": "admin" }, "createdDate": "2014-10-27T11:57:01.915+1100", "latest": true }, "id": "589828", "space": { "_expandable": { "description": "", "homepage": "/rest/api/content/589828", "icon": "" }, "_links": { "self": "http://localhost:8080/confluence/rest/api/space/TEST" }, "id": 753665, "key": "TEST", "name": "Test Space", "type": "global" }, "status": "current", "title": "Test Space Home", "type": "page", "version": { "by": { "displayName": "Gil Admin", "profilePicture": { "height": 48, "isDefault": true, "path": "/s/en_GB/5723/dfa6f4056bde4993312ffa3cb0f626ca41e68821.1/_/images/icons/profilepics/default.png", "width": 48 }, "type": "known", "userKey": "2c968271494ecbb701494ecc80dd0002", "username": "admin" }, "minorEdit": false, "number": 5, "when": "2014-10-27T16:09:24.368+1100" } }
aliases:
A lot of the time, when you're making calls to the Confluence REST API, there'll be a lot of results to return. For that reason, we paginate the results to make sure responses are easier to handle.
Let's say your initial call is asking for all the pages in a Confluence instance; the result could be a massive response with hundreds of thousands of pages. That's not a good place to start.
Rather than that, we've built in a default limit on results, but we recommend you always explicitly set the limit parameter to ensure you know how many results per page you'll get. Don't rely on the defaults as they'll be different depending on what parts of the response you're expanding, so the response you get might not be what you expected.
For example, you might need to request all pages in the Demonstration space (ds is the spaceKey) of your Confluence instance, but you only want the results 5 at a time. The endpoint we're going to hit here to specifically get the pages in that space is /rest/api/space/{spaceKey}/content/{type}, with the type being page (you could also use blogpost).
Your GET would look something like this:
1 2curl -u admin:admin -X GET "http://localhost:8080/confluence/rest/api/space/ds/content/page?limit=5" | python -mjson.tool
Note the limit parameter in this call is set to 5, so the response shows items 0 through 4.
1 2{ "_links": { "base": "http://localhost:8080/confluence", "context": "", "next": "/rest/api/space/ds/content/page?limit=5&start=5", "self": "http://localhost:8080/confluence/rest/api/space/ds/content/page" }, "limit": 5, "results": [ { "_expandable": { "ancestors": "", "body": "", "children": "/rest/api/content/98308/child", "container": "", "descendants": "/rest/api/content/98308/descendant", "history": "/rest/api/content/98308/history", "metadata": "", "space": "/rest/api/space/ds", "version": "" }, "_links": { "self": "http://localhost:8080/confluence/rest/api/content/98308", "tinyui": "/x/BIAB", "webui": "/pages/viewpage.action?pageId=98308" }, "id": "98308", "status": "current", "title": "What is Confluence? (step 1 of 9)", "type": "page" }, { "_expandable": { "ancestors": "", "body": "", "children": "/rest/api/content/98309/child", "container": "", "descendants": "/rest/api/content/98309/descendant", "history": "/rest/api/content/98309/history", "metadata": "", "space": "/rest/api/space/ds", "version": "" }, "_links": { "self": "http://localhost:8080/confluence/rest/api/content/98309", "tinyui": "/x/BYAB", "webui": "/pages/viewpage.action?pageId=98309" }, "id": "98309", "status": "current", "title": "A quick look at the editor (step 2 of 9)", "type": "page" }, { "_expandable": { "ancestors": "", "body": "", "children": "/rest/api/content/98306/child", "container": "", "descendants": "/rest/api/content/98306/descendant", "history": "/rest/api/content/98306/history", "metadata": "", "space": "/rest/api/space/ds", "version": "" }, "_links": { "self": "http://localhost:8080/confluence/rest/api/content/98306", "tinyui": "/x/AoAB", "webui": "/pages/viewpage.action?pageId=98306" }, "id": "98306", "status": "current", "title": "Get serious with a table (step 5 of 9)", "type": "page" }, { "_expandable": { "ancestors": "", "body": "", "children": "/rest/api/content/98307/child", "container": "", "descendants": "/rest/api/content/98307/descendant", "history": "/rest/api/content/98307/history", "metadata": "", "space": "/rest/api/space/ds", "version": "" }, "_links": { "self": "http://localhost:8080/confluence/rest/api/content/98307", "tinyui": "/x/A4AB", "webui": "/display/ds/Welcome+to+Confluence" }, "id": "98307", "status": "current", "title": "Welcome to Confluence", "type": "page" }, { "_expandable": { "ancestors": "", "body": "", "children": "/rest/api/content/98305/child", "container": "", "descendants": "/rest/api/content/98305/descendant", "history": "/rest/api/content/98305/history", "metadata": "", "space": "/rest/api/space/ds", "version": "" }, "_links": { "self": "http://localhost:8080/confluence/rest/api/content/98305", "tinyui": "/x/AYAB", "webui": "/pages/viewpage.action?pageId=98305" }, "id": "98305", "status": "current", "title": "Share your page with a team member (step 9 of 9)", "type": "page" } ], "size": 5, "start": 0 }
In the above response, line 5 shows the link for the next page of results (/rest/api/space/ds/content/page?limit=5&start=5). Note there's no previous link in the response, meaning there's no results before this page.
You can then make a call to return the next page. The start parameter in the next link is 5, so the next page of results will show items 5 through 9.
The call will be as follows:
1 2curl -u admin:admin -X GET "http://localhost:8080/confluence/rest/api/space/ds/content/page?limit=5&start=5" | python -mjson.tool
Which will deliver the next set of results, this time with links for the next and previous pages.
1 2{ "_links": { "base": "http://localhost:8080/confluence", "context": "", "next": "/rest/api/space/ds/content/page?limit=5&start=10", "prev": "/rest/api/space/ds/content/page?limit=5&start=0", "self": "http://localhost:8080/confluence/rest/api/space/ds/content/page" }, "limit": 5, "results": [ { "_expandable": { "ancestors": "", "body": "", "children": "/rest/api/content/98314/child", "container": "", "descendants": "/rest/api/content/98314/descendant", "history": "/rest/api/content/98314/history", "metadata": "", "space": "/rest/api/space/ds", "version": "" }, "_links": { "self": "http://localhost:8080/confluence/rest/api/content/98314", "tinyui": "/x/CoAB", "webui": "/pages/viewpage.action?pageId=98314" }, "id": "98314", "status": "current", "title": "Let's edit this page (step 3 of 9)", "type": "page" }, { "_expandable": { "ancestors": "", "body": "", "children": "/rest/api/content/98313/child", "container": "", "descendants": "/rest/api/content/98313/descendant", "history": "/rest/api/content/98313/history", "metadata": "", "space": "/rest/api/space/ds", "version": "" }, "_links": { "self": "http://localhost:8080/confluence/rest/api/content/98313", "tinyui": "/x/CYAB", "webui": "/pages/viewpage.action?pageId=98313" }, "id": "98313", "status": "current", "title": "Tell people what you think in a comment (step 8 of 9)", "type": "page" }, { "_expandable": { "ancestors": "", "body": "", "children": "/rest/api/content/98312/child", "container": "", "descendants": "/rest/api/content/98312/descendant", "history": "/rest/api/content/98312/history", "metadata": "", "space": "/rest/api/space/ds", "version": "" }, "_links": { "self": "http://localhost:8080/confluence/rest/api/content/98312", "tinyui": "/x/CIAB", "webui": "/pages/viewpage.action?pageId=98312" }, "id": "98312", "status": "current", "title": "Prettify the page with an image (step 4 of 9)", "type": "page" }, { "_expandable": { "ancestors": "", "body": "", "children": "/rest/api/content/98311/child", "container": "", "descendants": "/rest/api/content/98311/descendant", "history": "/rest/api/content/98311/history", "metadata": "", "space": "/rest/api/space/ds", "version": "" }, "_links": { "self": "http://localhost:8080/confluence/rest/api/content/98311", "tinyui": "/x/B4AB", "webui": "/pages/viewpage.action?pageId=98311" }, "id": "98311", "status": "current", "title": "Lay out your page (step 6 of 9)", "type": "page" }, { "_expandable": { "ancestors": "", "body": "", "children": "/rest/api/content/98310/child", "container": "", "descendants": "/rest/api/content/98310/descendant", "history": "/rest/api/content/98310/history", "metadata": "", "space": "/rest/api/space/ds", "version": "" }, "_links": { "self": "http://localhost:8080/confluence/rest/api/content/98310", "tinyui": "/x/BoAB", "webui": "/pages/viewpage.action?pageId=98310" }, "id": "98310", "status": "current", "title": "Learn the wonders of autoconvert (step 7 of 9)", "type": "page" } ], "size": 5, "start": 5 }
When the response doesn't contain a link to the next page of results, you know that you've reached the end. Below you'll see the call for the next page of results, and the response which doesn't contain a next link.
1 2curl -u admin:admin -X GET "http://localhost:8080/confluence/rest/api/space/ds/content/page?limit=5&start=10" | python -mjson.tool
1 2{ "_links": { "base": "http://localhost:8080/confluence", "context": "", "prev": "/rest/api/space/ds/content/page?limit=5&start=5", "self": "http://localhost:8080/confluence/rest/api/space/ds/content/page" }, "limit": 5, "results": [ { "_expandable": { "ancestors": "", "body": "", "children": "/rest/api/content/589845/child", "container": "", "descendants": "/rest/api/content/589845/descendant", "history": "/rest/api/content/589845/history", "metadata": "", "space": "/rest/api/space/ds", "version": "" }, "_links": { "self": "http://localhost:8080/confluence/rest/api/content/589845", "tinyui": "/x/FQAJ", "webui": "/display/ds/The+eleventh+page" }, "id": "589845", "status": "current", "title": "The eleventh page", "type": "page" } ], "size": 1, "start": 10 }
Rate this page: