• Introduction
• XML-RPC
• SOAP
• Remote Methods
• Data Objects
• Notes
• Scripts Examples
• Changelog

Introduction

Confluence provides remote APIs as both XML-RPC and SOAP. This document refers to the XML-RPC specification, see SOAP details below. XML-RPC and SOAP are both remote choices, as they have bindings for almost every language making them very portable.

Which should I use?

• SOAP is generally more useful from a strongly typed language (like Java or C#) but these require more setup.
• XML-RPC is easier to use from a scripting language (like Perl, Python, AppleScript etc) and hence is often quicker to use.

  Looking for the JIRA remote APIs? They are here.

XML-RPC Information

Some borrowed from the VPWik specification):

• The URL for XML-RPC requests is http://<<confluence-install>>/rpc/xmlrpc .
• All XML-RPC methods must be prefixed by confluence1. - to indicate this is version 1 of the API. We might introduce another version in the future. For example to call the getPage method, the method name is confluence1.getPage .
• All keys in structs are case sensitive.
• All strings are passed as UTF-8, and not ASCII per the XML-RPC update on 6/30/2003
• Confluence uses 64 big long values for things like object IDs, but XML-RPC's largest supported numeric type is int32. As such, all IDs and other long values must be converted to Strings when passed through XML-RPC API.
• Anywhere you see the word Vector, you can interchange it with "Array" or "List" depending on what language you prefer. This is the array data type as defined in the XML-RPC spec.
• Anywhere you see the word Hashtable, you can interchange it with "Struct" or "Dictionary" or "Map" depending on what language you prefer. This is the struct data type as defined in the XML-RPC spec.
• The default session lifetime is 30 minutes, but that can be controlled by the deployer from the applicationContext.xml file.

SOAP Information

The SOAP API follows the same methods as below, except with typed objects (as SOAP allows for).

To find out more about the SOAP API, simply point your SOAP 'stub generator' at the WSDL file, located at http://<confluence-install>/rpc/soap-axis/confluenceservice-v1?wsdl .

For reference, the confluence.atlassian.com WSDL file is here.

Remote Methods

Authentication Methods

• String login(String username, String password) - login a user. Returns a String authentication token to be passed as authentication to all other remote calls. It's not bulletproof auth, but it will do for now. Must be called before any other method in a 'remote conversation'. From 1.3 onwards, you can supply an empty string as the token to be treated as being the anonymous user.
• boolean logout(String token) - remove this token from the list of logged in tokens. Returns true if the user was logged out, false if they were not logged in in the first place (we don't really need this return, but void seems to kill XML-RPC for me)

Administration

• String exportSite(String token, boolean exportAttachments) - exports a Confluence instance and returns a String holding the URL for the download. The boolean argument indicates whether or not attachments ought to be included in the export.
• ClusterInformation getClusterInformation(String token) - returns information about the cluster this node is part of.
• Vector getClusterNodeStatuses(String token) - returns a Vector of NodeStatus objects containing information about each node in the cluster.

General

• ServerInfo getServerInfo(String token) - retrieve some basic information about the server being connected to. Useful for clients that need to turn certain features on or off depending on the version of the server. (Since 1.0.3)

Spaces

Retrieval

• Vector getSpaces(String token) - returns all the SpaceSummaries that the current user can see.
• Space getSpace(String token, String spaceKey) - returns a single Space.
• String exportSpace(String token, String spaceKey, String exportType) - exports a space and returns a String holding the URL for the download. The export type argument indicates whether or not to export in XML, PDF, or HTML format - use "TYPE_XML", "TYPE_PDF", or "TYPE_HTML" respectively. Also, using "all" will select TYPE_XML.

Management

• Space addSpace(String token, Space space) - create a new space, passing in name, key and description.
• Boolean removeSpace(String token, String spaceKey) - remove a space completely.
• Space addPersonalSpace(String token, Space personalSpace, String userName) - add a new space as a personal space.
• boolean convertToPersonalSpace(String token, String userName, String spaceKey, String newSpaceName, boolean updateLinks) - convert an existing space to a personal space.

Pages

Retrieval

• Vector getPages(String token, String spaceKey) - returns all the PageSummaries in the space. Doesn't include pages which are in the Trash. Equivalent to calling Space.getCurrentPages().

• Page getPage(String token, String pageId) - returns a single Page
• Page getPage(String token, String spaceKey, String pageTitle) - returns a single Page
• Vector getPageHistory(String token, String pageId) - returns all the PageHistorySummaries - useful for looking up the previous versions of a page, and who changed them.
• Vector getPagePermissions(String token, String pageId) - returns the page level permissions for this page (since 1.4)

Dependencies

• Vector getAttachments(String token, String pageId) - returns all the Attachments for this page (useful to point users to download them with the full file download URL returned).
• Vector getAncestors(String token, String pageId) - returns all the ancestors (as PageSummaries) of this page (parent, parent's parent etc).
• Vector getChildren(String token, String pageId) - returns all the direct children (as PageSummaries) of this page.
• Vector getDescendents(String token, String pageId) - returns all the descendents (as PageSummaries) of this page (children, children's children etc).
• Vector getComments(String token, String pageId) - returns all the comments for this page.
• Comment getComment(String token, String commentId) - returns an individual comment.
• Comment addComment(String token, Comment comment) - adds a comment to the page.
• boolean removeComment(String token, String commentId) - removes a comment from the page.

Management

• Page storePage(String token, Page page) - add or update a page. For adding, the Page given as an argument should have space, title and content fields at a minimum. For updating, the Page given should have id, space, title, content and version fields at a minimum. The parentId field is always optional. All other fields will be ignored.
• String renderContent(String token, String spaceKey, String pageId, String content) - returns the HTML rendered content for this page. If 'content' is provided, then that is rendered as if it were the body of the page (useful for a 'preview page' function). If it's not provided, then the existing content of the page is used instead (ie useful for 'view page' function).
• String renderContent(String token, String spaceKey, String pageId, String content, Hashtable parameters) - Like the above renderContent(), but you can supply an optional hash (map, dictionary, etc) containing additional instructions for the renderer. Currently, only one such parameter is supported:
  • "style = clean" Setting the "style" parameter to "clean" will cause the page to be rendered as just a single block of HTML within a div, without the HTML preamble and stylesheet that would otherwise be added.
• void removePage(String token, String pageId) - remove a page

Attachments - new in version 2.0

Retrieval

• Attachment getAttachment(String token, String pageId, String fileName, String versionNumber) - get information about an attachment.
• byte[] getAttachmentData(String token, String pageId, String fileName, String versionNumber) - get the contents of an attachment.

Management

• Attachment addAttachment(String token, long contentId, Attachment attachment, byte[] attachmentData) - add a new attachment to a content entity object. Note that this uses a lot of memory - about 4 times the size of the attachment. The 'long contentId' is actually a String pageId for XML-RPC.
• boolean removeAttachment(String token, String contentId, String fileName) - remove an attachment from a content entity object.
• boolean moveAttachment(String token, String originalContentId, String originalName, String newContentEntityId, String newName) - move an attachment to a different content entity object and/or give it a new name.

Blog Entries

• Vector getBlogEntries(String token, String spaceKey) - returns all the BlogEntrySummaries in the space.
• BlogEntry getBlogEntry(String token, String pageId) - returns a single BlogEntry.
• BlogEntry storeBlogEntry(String token, BlogEntry entry) - add or update a blog entry. For adding, the BlogEntry given as an argument should have space, title and content fields at a minimum. For updating, the BlogEntry given should have id, space, title, content and version fields at a minimum. All other fields will be ignored.
• BlogEntry getBlogEntryByDayAndTitle(String token, String spaceKey, int dayOfMonth, String postTitle) - Retrieves a blog post in the Space with the given spaceKey, with the title 'postTitle' and posted on the day 'dayOfMonth'.

Search

• Vector search(String token, String query, int maxResults) - return a list of SearchResults which match a given search query (including pages and other content types). This is the same as a performing a parameterised search (see below) with an empty parameter map.
• Vector search(String token, String query, Map parameters, int maxResults) - (since 1.3) like the previous search, but you can optionally limit your search by adding parameters to the parameter map. If you do not include a parameter, the default is used instead.

Parameters for Limiting Search Results

Security

• Vector getPermissions(String token, String spaceKey) - Returns a Vector of Strings representing the permissions the current user has for this space (a list of "view", "modify", "comment" and / or "admin").
• Vector getPermissionsForUser(String token, String spaceKey, String userName) - Returns a Vector of Strings representing the permissions the given user has for this space. (since 2.1.4)
• Vector getPagePermissions(String token, String pageId) - Returns a Vector of Permissions representing the permissions set on the given page.
• Vector getSpaceLevelPermissions(String token) - returns all of the space level permissions which may be granted. This is a list of possible permissions to use with addPermissionToSpace, below, not a list of current permissions on a Space.
• boolean addPermissionToSpace(String token, String permission, String remoteEntityName, String spaceKey) - Give the entity named remoteEntityName (either a group or a user) the permission permission on the space with the key spaceKey.
• boolean addPermissionsToSpace(String token, Vector permissions, String remoteEntityName, String spaceKey) - Give the entity named remoteEntityName (either a group or a user) the permissions permissions on the space with the key spaceKey.
• boolean removePermissionFromSpace(String token, String permission, String remoteEntityName, String spaceKey) - Remove the permission permission} from the entity named {{remoteEntityName (either a group or a user) on the space with the key spaceKey.
• boolean addAnonymousPermissionToSpace(String token, String permission, String spaceKey) - Give anonymous users the permission permission on the space with the key spaceKey. (since 2.0)

• boolean addAnonymousPermissionsToSpace(String token, Vector permissions, String spaceKey) - Give anonymous users the permissions permissions on the space with the key spaceKey. (since 2.0)
• boolean removeAnonymousPermissionFromSpace(String token, String permission,String spaceKey) - Remove the permission permission} from anonymous users on the space with the key {{spaceKey. (since 2.0)
• boolean removeAllPermissionsForGroup(String token, String groupname) - Remove all the global and space level permissions for groupname.

User Management

• User getUser(String token, String username) - get a single user
• void addUser(String token, User user, String password) - add a new user with the given password
• void addGroup(String token, String group) - add a new group
• Vector getUserGroups(String token, String username) - get a user's current groups
• void addUserToGroup(String token, String username, String groupname) - add a user to a particular group
• boolean removeUserFromGroup(String token, String username, String groupname) - remove a user from a group.
• boolean removeUser(String token, String username) - delete a user.
• boolean removeGroup(String token, String groupname, String defaultGroupName) - remove a group. If defaultGroupName is specified, users belonging to groupname will be added to defaultGroupName.
• Vector getGroups(String token) - gets all groups
• boolean hasUser(String token,  String username) - checks if a user exists
• boolean hasGroup(String token, String groupname) - checks if a group exists
• boolean editUser(String token, RemoteUser remoteUser) - edits the details of a user
• boolean deactivateUser(String token, String username) - deactivates the specified user
• boolean reactivateUser(String token, String username) - reactivates the specified user
• Vector getActiveUsers(String token, boolean viewAll) - returns all registered users
• boolean setUserInformation(String token, UserInformation userInfo) - updates user information
• UserInformation getUserInformation(String token, String username) - Retrieves user information
• boolean changeMyPassword(String token, String oldPass, String newPass) - changes the current user's password
• boolean changeUserPassword(String token, String username, String newPass) - changes the specified user's password
• boolean addProfilePicture(String token, String userName, String fileName, String mimeType, byte[] pictureData) - add and set the profile picture for a user.

Labels

• Vector getLabelsById(String token, long objectId) - Returns all Labels for the given ContentEntityObject ID
• Vector getMostPopularLabels(String token, int maxCount) - Returns the most popular Labels for the Confluence instance, with a specified maximum number.
• Vector getMostPopularLabelsInSpace(String token, String spaceKey, int maxCount) - Returns the most popular Labels for the given spaceKey, with a specified maximum number of results.
• Vector getRecentlyUsedLabels(String token, int maxResults) - Returns the recently used Labels for the Confluence instance, with a specified maximum number of results.
• Vector getRecentlyUsedLabelsInSpace(String token, String spaceKey, int maxResults) - Returns the recently used Labels for the given spaceKey, with a specified maximum number of results.
• Vector getSpacesWithLabel(String token, String labelName) - Returns an array of Spaces that have been labelled with labelName.
• Vector getRelatedLabels(String token, String labelName, int maxResults) - Returns the Labels related to the given label name, with a specified maximum number of results.
• Vector getRelatedLabelsInSpace(String token, String labelName, String spaceKey, int maxResults) - Returns the Labels related to the given label name for the given spaceKey, with a specified maximum number of results.
• Vector getLabelsByDetail(String token, String labelName, String namespace, String spaceKey, String owner) - Retrieves the Labels matching the given labelName, namespace, spaceKey or owner.
• Vector getLabelContentById(String token, long labelId) - Returns the content for a given label ID
• Vector getLabelContentByName(String token, String labelName) - Returns the content for a given label name.
• Vector getLabelContentByObject(String token, Label labelObject) - Returns the content for a given Label object.
• Vector getSpacesContainingContentWithLabel(String token, String labelName) - Returns all Spaces that have content labelled with labelName.
• boolean addLabelByName(String token, String labelName, long objectId) - Adds label(s) to the object with the given ContentEntityObject ID. For multiple labels, labelName should be in the form of a space-separated or comma-separated string.
• boolean addLabelById(String token, long labelId, long objectId) - Adds a label with the given ID to the object with the given ContentEntityObject ID.
• boolean addLabelByObject(String token, Label labelObject, long objectId) - Adds the given label object to the object with the given ContentEntityObject ID.
• boolean addLabelByNameToSpace(String token, String labelName, String spaceKey) - Adds a label to the object with the given ContentEntityObject ID.
• boolean removeLabelByName(String token, String labelName, long objectId) - Removes the given label from the object with the given ContentEntityObject ID.
• boolean removeLabelById(String token, long labelId, long objectId) - Removes the label with the given ID from the object with the given ContentEntityObject ID.
• boolean removeLabelByObject(String token, Label labelObject, long objectId) - Removes the given label object from the object with the given ContentEntityObject ID.
• boolean removeLabelByNameFromSpace(String token, String labelName, String spaceKey) - Removes the given label from the given spaceKey.

Data Objects

Most returned structs have a summary and a detailed form:

• The summary form is a primary key (ie space key, page id) and a representative form (ie space name, page title)
• The detailed form will have all of the entity details as might be needed for the client.

Unless otherwise specified, all returned structs are in detailed form.

ServerInfo

Note: Version 1.0.3 of Confluence would be major-version: 1, minor-version: 0, patch-level: 3. Version 2.0 would have a patch-level of 0, even if it's not visible in the version number.

SpaceSummary

Space

PageSummary

Page

PageHistorySummary

BlogEntrySummary

BlogEntry

RSS Feed

Search Result

Attachment

Comment

User

Permission

Label

UserInformation

ClusterInformation

NodeStatus

Script Examples

The Confluence Extension space contains various examples of scripts

Changelog

2.3

• Added getClusterInformation and getClusterNodeStatuses. 

2.2

• Added addPersonalSpace, convertToPersonalSpace and addProfilePicture.

2.1.4

• Added getPermissionsForUser.

2.0

• Updated getLocks() to getPagePermissions()
• Added addAttachment, getAttachment, getAttachmentData, removeAttachment and moveAttachment methods to allow remote attachment handling. Note that adding large attachments with this API uses a lot of memory during the addAttachment operation.
• Added addAnonymousPermissionToSpace, addAnonymousPermissionsToSpace and removeAnonymousPermissionFromSpace.
• Added the addComment and removeComment methods for comment manipulation.
• Added hasGroup and hasUser methods to determine if a group or user exists.
• Added editUser method.
• Added ability to deactivate and reactivate users.
• Added getActiveUsers method to retrieve a user list.
• Added ability to change the user password.
• Added ability to retrieve and modify user information.
• Added ability to retrieve, add and remove labels.
• Added getBlogEntryByDayAndTitle

1.4

• Added new exportSpace and exportSite methods to build exports of an individual space or an entire Confluence instance and return with a URL leading to the download.
• Added new getChildren and getDescendents methods to get the direct children and all descendents of a given page.
• Added new getAncestors method to get the ancestors of a given page.
• Removed the old getLocks as locks are superceded by page level permissions.
• Added new getPagePermissions method to retrieve page level permissions.
• Added new removeUser, removeGroup, removeAllPermissionsForGroup, addUserToGroup and removeUserFromGroup methods.
• Added new addPermissionToSpace method.
• Added new Permission data object.
• Added new getSpaceLevelPermissions method.

1.3

• Added new getPage method which retrieves a page by space key and page title.
• Added new removeSpace method to remove an entire space.
• Added ability to limit search by parameters.
• Allow anonymous access.

1.2

• renderContent takes an optional hashtable for rendering hints, the only one supported right now is "style=clean"

1.1

• getLocks gives you back a list of any locks that apply to a given page
• added a locks field to the various Page structs containing a count of any applicable page-level locks
• CRUD methods added for blog-posts

1.0.3

• getServerInfo gives you some basic information about the server version CONF1123
• storePage now allows you to change the page's name (incoming links are all renamed) CONF-974
• storePage now reliably allows you to re-parent pages
• WSDL now respects the server's configured base URL, allowing it to work on proxy-hosted servers CONF-1088