XML-RPC
Get It Working
Set the
remote option to enable XML-RPC in the Configuration Settings “Authentication” section
Set the
remoteuser option with a mix of comma separated “usernames,groups”
For security reasons it's safer to allow access to the XML-RPC over HTTPS only. DokuWiki's .htaccess.dist
contains some rewrite rules to do that.
You might need to install an XML package like php-xml
(on debian)
Accessing The XML-RPC Interface
You can access the XML-RPC interface via the following URLs:
http://<your wiki/domain/ip>/lib/exe/xmlrpc.php
or
https://<your wiki/domain/ip>/lib/exe/xmlrpc.php
Here are some Samples of Clients using the XML-RPC Api to test with
Sample XML Requests
You should use an XML-RPC library instead of hand-crafting your requests.
Here is an example of how to post to the API:
POST /RPC2 HTTP/1.0
User-Agent: Frontier/5.1.2 (WinNT)
Host: betty.userland.com
Content-Type: text/xml
Content-length: 181
<?xml version="1.0"?>
<methodCall>
<methodName>examples.getStateName</methodName>
<params>
<param>
<value>
<i4>41</i4>
</value>
</param>
</params>
</methodCall>
<?xml version="1.0"?>
<methodCall>
<methodName>dokuwiki.getVersion</methodName>
</methodCall>
example put page
<?xml version="1.0"?>
<methodCall>
<methodName>wiki.putPage</methodName>
<params>
<param>
<value>
<string>myputpage
</string>
</value>
</param>
<param>
<value>
<string>This is my page content</string>
</value>
</param>
<param>
<value>
<struct>
<member>
<name>sum</name>
<value><string>Spiceworks</string></value>
</member>
<member>
<name>minor</name>
<value><boolean>True</boolean></value>
</member>
</struct>
</value>
</param>
</params>
</methodCall>
Available Functions
Functions are listed in the following format:
Name | The name of the function |
Parameters | A list of parameters to pass to the function |
Data | The type of the returned data |
Description | Short explanation what the function does |
Since | The DokuWiki (and XML-RPC API Version) this function was introduced |
dokuwiki.getPagelist
Name | dokuwiki.getPagelist |
Parameters | (string) namespace, (array) options |
Data | (array) list of page items |
Description | Lists all pages within a given namespace. The options are passed directly to search_allpages(). |
Since | 2009-03-06 (1) |
dokuwiki.getVersion
Name | dokuwiki.getVersion |
Parameters | - |
Data | (string) version number |
Description | Returns the DokuWiki version of the remote Wiki. |
dokuwiki.getTime
Name | dokuwiki.getTime |
Parameters | - |
Data | (int) timestamp |
Description | Returns the current time at the remote wiki server as Unix timestamp. |
Since | 2009-03-06 (1) |
dokuwiki.getXMLRPCAPIVersion
Name | dokuwiki.getXMLRPCAPIVersion |
Parameters | - |
Data | (int) version number |
Description | Returns the XML RPC interface version of the remote Wiki. This is DokuWiki implementation specific and independent of the supported standard API version returned by wiki.getRPCVersionSupported. |
Since | 2009-03-06 (1) |
dokuwiki.login
Name | dokuwiki.login |
Parameters | (string) user, (string) password |
Data | (boolean) login successful |
Description | Uses the provided credentials to execute a login and will set cookies. This can be used to make authenticated requests afterwards. Your client needs to support cookie handling. Alternatively use HTTP basic auth credentials. |
Since | 2009-03-06 (1) |
dokuwiki.search
Name | dokuwiki.search |
Parameters | (string) a query string as described on search |
Data | (array) associative array with matching pages similar to what is returned by dokuwiki.getPagelist , snippets are provided for the first 15 results |
Description | Performs a fulltext search. |
Since | 2010-02-28 (3) |
dokuwiki.getTitle
Name | dokuwiki.getTitle |
Parameters | - |
Data | (string) the title of the wiki |
Description | Returns the title of the wiki. |
Since | 2010-04-18 (4) |
dokuwiki.appendPage
Name | dokuwiki.appendPage |
Parameters | (string) pagename, (string) raw Wiki text, (array) attrs
Where attrs can contain the following:
$attrs['sum'] = (string) change summary
$attrs['minor'] = (boolean) minor
|
Data | (boolean) |
Description | Appends text to a Wiki Page. |
Since | 2010-11-20 (5) |
dokuwiki.setLocks
Name | dokuwiki.setLocks |
Parameters | (array) list of two lists of page ids [
'lock' => [...],
'unlock' => [...]
]
|
Data | (array) array with 4 lists of pageids [
'locked' => [...],
'lockfail' => [...],
'unlocked' => [...],
'unlockfail' => [...]
]
|
Description | Allows you to lock or unlock a whole bunch of pages at once. Useful when you are about to do an operation over multiple pages. |
Since | 2009-03-06 (1) |
dokuwiki.createUser
Name | dokuwiki.createUser |
Parameters | (array) parameters, where parameters can contain: $params = [
'user' => 'username',
'password' => 'password1',
'name' => 'User Name',
'mail' => 'user@example.com',
'groups' => [
'user',
'test'
],
'notify' => false
]
|
Data | (bool) true if the user is created |
Description | Create a user. Returns 400 range error codes if input is not accepted. |
Since | 2022-06-24 |
dokuwiki.deleteUsers
Name | dokuwiki.deleteUsers |
Parameters | (array) list of usernames to delete |
Data | (bool) true if the users were deleted |
Description | Allows you to delete one or more users. Useful to implement GDPR right to be forgotten tools. |
Since | 2018-05-24 |
wiki.getRPCVersionSupported
Name | wiki.getRPCVersionSupported |
Parameters | - |
Data | (string) version number |
Description | Returns 2 with the supported RPC API version. |
wiki.aclCheck
Name | wiki.aclCheck |
Parameters | (string) pagename |
Data | (int) Permissions of given wiki page |
Description | Returns the permission of the given wikipage. |
wiki.getPage
Name | wiki.getPage |
Parameters | (string) pagename |
Data | (string) raw Wiki text |
Description | Returns the raw Wiki text for a page. |
wiki.getPageVersion
Name | wiki.getPageVersion |
Parameters | (string) pagename, (int) Timestamp |
Data | (string) raw Wiki text |
Description | Returns the raw Wiki text for a specific revision of a Wiki page. |
wiki.getPageVersions
Name | wiki.getPageVersions |
Parameters | (string) pagename, (int) offset |
Data | (array) each array item holds the following data:
$data['user'] = username
$data['ip'] = ip address
$data['type'] = type of change
$data['sum'] = summary
$data['modified'] = modification date as IXR_Date Object
$data['version'] = page version as timestamp
|
Description | Returns the available versions of a Wiki page. The number of pages in the result is controlled via the recent configuration setting. The offset can be used to list earlier versions in the history. |
wiki.getPageInfo
Name | wiki.getPageInfo |
Parameters | (string) pagename |
Data | (array) an array containing the following data:
$data['name'] = [[:pagename]]
$data['lastModified'] = modification date as IXR_Date Object
$data['author'] = author of the Wiki page.
$data['version'] = page version as timestamp
|
Description | Returns information about a Wiki page. |
wiki.getPageInfoVersion
Name | wiki.getPageInfoVersion |
Parameters | (string) pagename, (int) timestamp |
Data | (array) an array containing the following data:
$data['name'] = [[:pagename]]
$data['lastModified'] = modification date as UTC timestamp
$data['author'] = author of the Wiki page.
$data['version'] = page version as timestamp
|
Description | Returns information about a specific version of a Wiki page. |
wiki.getPageHTML
Name | wiki.getPageHTML |
Parameters | (string) pagename |
Data | (string) rendered HTML |
Description | Returns the rendered XHTML body of a Wiki page. |
wiki.getPageHTMLVersion
Name | wiki.getPageHTMLVersion |
Parameters | (string) pagename, (int) timestamp |
Data | (string) rendered HTML |
Description | Returns the rendered HTML of a specific version of a Wiki page. |
wiki.putPage
Name | wiki.putPage |
Parameters | (string) pagename, (string) raw Wiki text, (array) attrs
Where attrs can contain the following:
$attrs['sum'] = (string) change summary
$attrs['minor'] = (boolean) minor
|
Data | (boolean) |
Description | Saves a Wiki Page. |
wiki.listLinks
Name | wiki.listLinks |
Parameters | (string) pagename |
Data | (array) each array item holds the following data:
$data['type'] = local/extern
$data['page'] = the wiki page (or the complete URL if extern)
$data['href'] = the complete URL
|
Description | Returns a list of all links contained in a Wiki page. |
wiki.getAllPages
Name | wiki.getAllPages |
Parameters | - |
Data | (array) One item for each page, each item containing the following data:
$data['id'] = id of the page
$data['perms'] = integer denoting the permissions on the page
$data['size'] = size in bytes
$data['lastModified'] = dateTime object of last modification date
|
Description | Returns a list of all Wiki pages in the remote Wiki. |
wiki.getBackLinks
Name | wiki.getBackLinks |
Parameters | (string) pagename |
Data | (array) |
Description | Returns a list of backlinks of a Wiki page. |
wiki.getRecentChanges
Name | wiki.getRecentChanges |
Parameters | (int) timestamp |
Data | (array) each array item holds the following data:
$data['name'] = page id
$data['lastModified'] = modification date as UTC timestamp
$data['author'] = author
$data['version'] = page version as timestamp
|
Description | Returns a list of recent changes since given timestamp.
As stated in recent_changes: Only the most recent change for each page is listed, regardless of how many times that page was changed. |
Name | wiki.getRecentMediaChanges |
Parameters | (int) timestamp |
Data | (array) each array item holds the following data:
$data['name'] = media id
$data['lastModified'] = modification date as UTC timestamp
$data['author'] = author
$data['version'] = page version as timestamp
$data['perms'] = media permissions
$data['size'] = media size in bytes
|
Description | Returns a list of recent changed media since given timestamp. |
wiki.getAttachments
Name | wiki.getAttachments |
Parameters | (String) namespace, (array) options |
Data | (array) each array item holds the following data:
$data['id'] = media id
$data['file'] = name of the file
$data['size'] = size in bytes
$data['mtime'] = upload date as a timestamp
$data['lastModified'] = modification date as XML-RPC Date object
$data['isimg'] = true if file is an image, false otherwise
$data['writable'] = true if file is writable, false otherwise
$data['perms'] = permissions of file
|
Description | Returns a list of media files in a given namespace. The options are passed directly to search_media(). |
wiki.getAttachment
Name | wiki.getAttachment |
Parameters | (String) id |
Data | (string) the data of the file, encoded in base64 |
Description | Returns the binary data of a media file. |
wiki.getAttachmentInfo
Name | wiki.getAttachmentInfo |
Parameters | (String) id |
Data | (array) an array containing the following information about the file:
$data['size'] = size in bytes
$data['lastModified'] = modification date as XML-RPC Date object
|
Description | Returns information about a media file. |
wiki.putAttachment
Name | wiki.putAttachment |
Parameters | (String) id, (base64) data, (array) params
Available parameters are: $params['ow'] = true if file is to overwrite an already
existing media object of the given id.
|
Data | |
Description | Uploads a file as a given media id. |
wiki.deleteAttachment
Name | wiki.deleteAttachment |
Parameters | (String) id |
Data | |
Description | Deletes a file. Fails if the file is still referenced from any page in the wiki. |
plugin.acl.listAcls
Name | plugin.acl.listAcls |
Parameters | - |
Data | (array) of ACLs {scope, user, permission}' |
Description | Get the list of all ACLs. |
plugin.acl.addAcl
Name | plugin.acl.addAcl |
Parameters | (String) scope, (String) username, (int) permission |
Data | (boolean) return true if the rule was correctly added |
Description | Add an ACL rule. Use @groupname instead of user to add an ACL rule for a group. |
plugin.acl.delAcl
Name | plugin.acl.delAcl |
Parameters | (String) scope, (String) username |
Data | (boolean) return true if the rules were correctly deleted |
Description | Delete any ACL rule matching the given scope and user. Use @groupname instead of user to delete the ACL rules for the group. |
Adding methods to the XML-RPC API
Use Remote Plugins to add other methods to the XML-RPC API.
A summary of recent plugins which indicate Remote support:
Name | Description | Remote plugins compatible with last two releases |
---|
ACL Plugin | Manage page and namespace access control list (ACL) settings (bundled with DokuWiki) | 1 | acl |
API Plugin | A plugin that implements a Rest API | 1 | api |
confmanager Plugin | Plugin to manage various .conf files | 1 | confmanager |
doxycode Plugin | Parse code snippets in dokuwiki with cross referencing to doxygen documentation. | 1 | doxycode |
JSON Data Plugin | Build JSON database inside DokuWiki page and use the data in the page | 1 | json |
struct Plugin | A new structured data plugin | 1 | struct |
TagFilter Plugin | Allows to create custom dropdown fields to easily filter pages based on tags | 1 | tagfilter |
∑ 7 plugins matching query
To implement such a plugin please have a look at the remote plugins development documentation.
XML-RPC Error Codes
Since XML-RPC API Version 7 (API Version 7 is since Release Adora Belle (2012-10-13)) useful hierarchical error codes have been introduced. The following error codes can be returned by the XML-RPC Interface:
Italic rows are just categories. Only normal printed rows are returned by the interface.
Additionally there are some server error codes that indicate some kind of server or XML-RPC failure. The codes are the following:
-32600 → Invalid XML-RPC request. Not conforming to specification.
-32601 → Requested method does not exist.
-32602 → Wrong number of parameters or invalid method parameters.
-32603 → Not authorized to call the requested method (No login or invalid login data was given).
-32604 → Forbidden to call the requested method (but a valid login was given).
-32605 → The XML-RPC
API has not been enabled in the configuration
-32700 → Parse Error. Request not well formed.
-32800 → Recursive calls to system.multicall are forbidden.
-99999 → Unknown server error.
Sample Clients