Resources · Documentation · API Reference

XML Web Service API

A legacy but fully-featured XML-over-HTTP API with 60+ commands for complete control over documents, folders, users, and sharing.

Reference Last Updated: May 2026 WebPal 4.2+

Introduction

The XML Web Service API is WebPal's original programmatic interface, providing comprehensive access to all document management operations. While considered legacy, it remains fully supported and offers the most complete feature set of any WebPal API.

Endpoint

POST https://YOURSERVER.webpal.net/webservice/xml-service.php
Content-Type: text/xml

All requests use HTTP POST with an XML body. Responses are XML (text/xml), except file downloads which return the file content with the appropriate MIME type.

Request Format

Parameters can be passed as attributes of the root <request> element or as child elements:

<!-- Parameters as attributes -->
<?xml version="1.0" encoding="UTF-8"?>
<request command="move"
    path="/dir/test1/file1"
    dir="/dir/testb1/testc1"
    sessionID="bd7d8af5ab41407dac6666874c74c3ab"/>

<!-- Parameters as elements -->
<?xml version="1.0" encoding="UTF-8"?>
<request command="upload" sessionID="bd7d8af5ab41407dac6666874c74c3ab">
    <dir><![CDATA[/dir/test1]]></dir>
    <name><![CDATA[file1]]></name>
    <title><![CDATA[a document title]]></title>
    <content><![CDATA[some text]]></content>
</request>

Response Format

<!-- Success -->
<?xml version="1.0" encoding="UTF-8"?>
<response status="ok">
    <result>
        <path>/dir/test1/file1</path>
    </result>
</response>

<!-- Failure -->
<?xml version="1.0" encoding="UTF-8"?>
<response status="fail">
    <error>Bad path /dir/testb1</error>
</response>

Authentication

Call login first to get a session ID, then pass it in all subsequent requests:

login

<request command="login" login="myuser" password="mypassword"/>

Response:

<response status="ok">
    <result sessionID="bd7d8af5ab41407dac6666874c74c3ab"/>
</response>

Pass the session ID as:

The sessionID attribute on the <request> element
The HTTP header X_DM_SESSION_ID

logout

<request command="logout" sessionID="..."/>

Common Parameters

Paths and IDs

The path parameter can be:

An internal integer ID (e.g., 695017313154591029)
A "pretty" symbolic path when pretty="true" (e.g., /System Drive/reports/file.csv)

Pretty paths are relative to the logged-in user's shares.

Boolean Parameters

Values recognised as true: 1, yes, true (case-insensitive).
Values recognised as false: everything else.

Paging and Sorting

Commands that return lists accept:

n or results — number of items to return (default: all)
offset — starting position (default: 0)
sort — comma-separated column:asc or column:desc pairs

Authentication Commands

Parameter	Type	Description
login	string	The username of the user logging in
password	string	The user's password

Returns: A sessionID element containing the session ID as text content. The response headers also contain a session cookie.

Example Request:

<?xml version="1.0"?>
<request command="login" login="myuser" password="mypassword"/>

Example Response:

<?xml version="1.0"?>
<response status="ok">
  <sessionID>eyJpdiI6Im5kRWpuOVdBZGVYZUFOUFE1Vk9JcGc9PSIsInZhbHVlIjoiVFdU...</sessionID>
  <version-string>3.6.9.- build 68 Thu, 21 Jul 2016 14:49:11 -0400</version-string>
  <build-number>68</build-number>
</response>

logout

Log out from the current session, clearing the session cookie.

Parameter	Type	Description
sessionID	string	The session ID to terminate

Returns: A response with status "ok" and no sub-elements.

Example Request:

<?xml version="1.0"?>
<request command="logout" sessionID="..."/>

Example Response:

<?xml version="1.0"?>
<response status="ok"/>

resetPassword

Reset a user's password and send an email to the registered email address if the email is known and unique.

Parameter	Type	Description
email	string	The email address for which to reset the password

Returns: A result element containing the supplied email address.

Example Request:

<?xml version="1.0"?>
<request command="resetPassword" email="user@example.com"/>

Example Response:

<?xml version="1.0"?>
<response status="ok">
  <result email="user@example.com"/>
</response>

File Operations

upload

Upload a new document to WebPal or add a new version to an existing document.

Parameter	Type	Description
sessionID	string	Session ID for authentication
dir	string	Destination folder ID or symbolic path
pretty	boolean	If true, interpret dir as a symbolic path
name	string	The name of the new file
fullPath	string	A subpath in dir into which to upload; folders are created if needed
addVersion	boolean	If true, add a new version; if false, rename if file exists
title	string	Document title metadata
comments	string	Document comments
replaceComments	boolean	Replace existing comments with new comments
content	string	File contents if no file in POST body
base64	boolean	Indicates content is base64 encoded
includeMetaData	boolean	If true, include full metadata in response

Returns: A result element containing a path element with the uploaded file's metadata.

Example Request:

<?xml version="1.0"?>
<request command="upload" sessionID="..." pretty="true" 
         name="report2.txt" dir="/sites/documents" includeMetaData="true">
  <content><![CDATA[File contents here]]></content>
</request>

Example Response:

<?xml version="1.0"?>
<response status="ok">
  <result>
    <path name="report2.txt" path="555442058122671091" title="" comments="" 
          draft="" review="" finalDraft="" permissions="8191" user="1" 
          modified="" isdirectory="No" size="8" 
          prettyName="/sites/documents/report2.txt" 
          iconPath="img/files/txt.gif" mime-type="text/plain" 
          version="1" parent="724663140926469594">555442058122671091</path>
  </result>
</response>

download

Stream the contents of a document to the output. Optionally watermark or stamp a PDF.

Parameter	Type	Description
sessionID	string	Session ID for authentication
path	string	Document ID or symbolic path
pretty	boolean	If true, interpret path as symbolic
version	integer	The desired version of the document
disposition	string	Either "inline" or "attachment"
resize	string	ImageMagick dimensions (e.g., "30x40")
watermark	string	Text of the watermark
watermark-position	string	One of: top, left, bottom, right, diagonal
watermark-font-name	string	Font name to use
watermark-font-size	integer	Font size
watermark-color	string	RGB as comma-separated (e.g., "255,0,0")
watermark-mode	string	One of: stamp, watermark

Returns: The contents of the document with appropriate MIME type.

Example Request:

<?xml version="1.0"?>
<request command="download" sessionID="..." pretty="true" 
         path="/sites/report2.txt"/>

append

Append text to an existing document.

Parameter	Type	Description
sessionID	string	Session ID for authentication
path	string	Document ID or symbolic path
pretty	boolean	If true, interpret path as symbolic
content	string	The text to append

Returns: A result element with a path element containing the updated document metadata.

Example Request:

<?xml version="1.0"?>
<request command="append" sessionID="..." pretty="yes" 
         path="/System Drive/report2.csv" content="x,y,z&#10;q,r,s&#10;"/>

Example Response:

<?xml version="1.0"?>
<response status="ok">
  <result>
    <path name="report2.csv" path="695017313154591029" title="" comments="" 
          draft="0" review="" finalDraft="0" permissions="8191" user="1" 
          modified="1,2020-06-08 16:56:08" isdirectory="No" size="48" 
          prettyName="/System Drive/report2.csv" iconPath="img/files/file.gif" 
          mime-type="text/csv" version="92" 
          parent="439541447604990017">695017313154591029</path>
  </result>
</response>

copy

Copy a document or folder to another folder.

Parameter	Type	Description
sessionID	string	Session ID for authentication
path	string	Source file/folder ID or symbolic path
pretty	boolean	If true, interpret path as symbolic
dir	string	Destination folder ID or path
overwrite	boolean	Allow overwriting existing file
renameIfConflict	boolean	Rename the copied file if there's a conflict
incr	boolean	Append a number to filename if conflict
ifExists	boolean	Don't error if source doesn't exist

Returns: A result containing a count element and a path element with the ID of the copied object.

Example Request:

<?xml version="1.0"?>
<request command="copy" sessionID="..." path="657080270669470254" 
         dir="945653219145194140" renameIfConflict="true"/>

Example Response:

<?xml version="1.0"?>
<response status="ok">
  <result>
    <count>1</count>
    <path>117090499569622314</path>
  </result>
</response>

move

Move a document or folder to another folder.

Parameter	Type	Description
sessionID	string	Session ID for authentication
path	string	Source file/folder ID or symbolic path
pretty	boolean	If true, interpret path as symbolic
dest	string	Destination folder ID or path
overwrite	boolean	Allow overwriting existing file
ifExists	boolean	Don't error if source doesn't exist

Returns: A result containing a count element and a path element with the ID of the moved object.

Example Request:

<?xml version="1.0"?>
<request command="move" sessionID="..." path="901554464601974166" 
         dir="478761745102601515" overwrite="true" ifExists="true"/>

Example Response:

<?xml version="1.0"?>
<response status="ok">
  <result>
    <count>1</count>
    <path>901554464601974166</path>
  </result>
</response>

delete

Delete a document or folder.

Parameter	Type	Description
sessionID	string	Session ID for authentication
path	string	File/folder ID or symbolic path to delete
pretty	boolean	If true, interpret path as symbolic
ifExists	boolean	Don't error if item doesn't exist

Returns: A result element containing the count of deleted items.

Example Request:

<?xml version="1.0"?>
<request command="delete" sessionID="..." path="945653219145194140"/>

Example Response:

<?xml version="1.0"?>
<response status="ok">
  <result>12</result>
</response>

rename

Rename a document or folder.

Parameter	Type	Description
sessionID	string	Session ID for authentication
path	string	File/folder ID or symbolic path
pretty	boolean	If true, interpret path as symbolic
name	string	The new name
ifExists	boolean	Don't error if item doesn't exist

Returns: A result containing a path element with the item's ID.

Example Request:

<?xml version="1.0"?>
<request command="rename" sessionID="..." path="116071415415952886" 
         name="the-new-name.txt"/>

Example Response:

<?xml version="1.0"?>
<response status="ok">
  <result>renamed<path>116071415415952886</path></result>
</response>

exists

Check if a file or folder exists. If an optional name is supplied, check if that subpath exists within the object.

Parameter	Type	Description
sessionID	string	Session ID for authentication
path	string	File/folder ID or symbolic path
pretty	boolean	If true, interpret path as symbolic
name	string	A subpath of the supplied path to check

Returns: A result element with an exists attribute ("yes" or "no").

Example Request:

<?xml version="1.0"?>
<request command="exists" sessionID="..." path="/System Drive" 
         name="some-file" pretty="true"/>

Example Response:

<?xml version="1.0"?>
<response status="ok">
  <result exists="no"/>
</response>

fileInfo

Return file metadata for the specified file(s). May return more than one result for shares of the same name.

Parameter	Type	Description
sessionID	string	Session ID for authentication
path	string	File/folder ID or symbolic path
pretty	boolean	If true, interpret path as symbolic
includeMetaData	boolean	Include full metadata in response

Returns: A result element containing one or more path elements with file metadata.

Example Request:

<?xml version="1.0"?>
<request command="fileInfo" sessionID="..." path="/System Drive/directory1" 
         pretty="true" includeMetaData="true"/>

Example Response:

<?xml version="1.0"?>
<response status="ok">
  <result>
    <path name="directory1" path="151037544713428608" title="" comments="" 
          draft="0" review="" finalDraft="0" permissions="8191" user="0" 
          modified="0,2020-02-09 13:53:29" isdirectory="Yes" size="4096" 
          prettyName="/System Drive/directory1" iconPath="img/files/dir.gif" 
          mime-type="" parent="439541447604990017">151037544713428608</path>
  </result>
</response>

fileCount

Compute counts of files and directories in a subtree.

Parameter	Type	Description
sessionID	string	Session ID for authentication
path	string	Folder ID or symbolic path
pretty	boolean	If true, interpret path as symbolic

Returns: A result element with dirs and files attributes, containing total count as text.

Example Request:

<?xml version="1.0"?>
<request command="fileCount" sessionID="..." path="151037544713428608"/>

Example Response:

<?xml version="1.0"?>
<response status="ok">
  <result dirs="54" files="295">349</result>
</response>

Folder Operations

createFolder

Create a folder. The path can contain "/" to create all folders in the path.

Parameter	Type	Description
sessionID	string	Session ID for authentication
name	string	The name of the folder to be created
dir	string	Parent folder ID or symbolic path
pretty	boolean	If true, interpret dir as symbolic path
includeMetaData	boolean	Include metadata in response
ifNotExists	boolean	Don't error if folder already exists

Returns: A result element containing a path element for the new folder.

Example Request:

<?xml version="1.0"?>
<request command="createFolder" sessionID="..." includeMetaData="true" 
         pretty="true" dir="/sites" name="new-folder"/>

Example Response:

<?xml version="1.0"?>
<response status="ok">
  <result>
    <path name="new-folder" path="724663140926469594" title="" comments="" 
          draft="" review="" finalDraft="" permissions="8191" user="0" 
          modified="" isdirectory="Yes" size="4096" 
          prettyName="/sites/new-folder" iconPath="img/files/dir.gif" 
          mime-type="" parent="124561914478016686">724663140926469594</path>
  </result>
</response>

listDirectory

List the directory contents. If the path is "/" and pretty is true, list the user's root shares.

Parameter	Type	Description
sessionID	string	Session ID for authentication
path	string	Folder ID or symbolic path
pretty	boolean	If true, interpret path as symbolic
includeMetaData	boolean	Include metadata in response
n / results	integer	Number of items to return
offset	integer	Starting position
sort	csv	Column:asc or column:desc pairs
files-only	boolean	Return only files
directories-only	boolean	Return only directories
pattern	string	Full text query string
filter	string	Substring to match in filenames
glob-pattern	string	Linux-like glob pattern for filtering

Returns: A result element containing path elements for each matching file or directory.

Example Request:

<?xml version="1.0"?>
<request command="listDirectory" sessionID="..." includeMetaData="true" 
         pretty="true" path="/System Drive/directory" files-only="true"/>

Example Response:

<?xml version="1.0"?>
<response status="ok">
  <result>
    <path name="image1.jpg" path="125220292151938759" title="" comments="" 
          draft="0" review="" finalDraft="0" permissions="8191" user="1" 
          modified="1,2020-02-08 14:32:58" isdirectory="No" size="13178" 
          prettyName="/System Drive/directory/image1.jpg" 
          iconPath="img/files/image.gif" mime-type="image/jpeg" version="1" 
          parent="187618080297490937">125220292151938759</path>
  </result>
</response>

listRoots

Return the root drives for the logged-in user.

Parameter	Type	Description
sessionID	string	Session ID for authentication
includeMetaData	boolean	Include metadata in response
n / results	integer	Number of items to return
offset	integer	Starting position
sort	csv	Column:asc or column:desc pairs

Returns: A result element containing path elements for each root drive.

Example Request:

<?xml version="1.0"?>
<request command="listRoots" sessionID="..." includeMetaData="true"/>

Example Response:

<?xml version="1.0"?>
<response status="ok">
  <result>
    <path name="sites" path="124561914478016686" title="" comments="" 
          draft="0" review="" finalDraft="0" permissions="8191" user="0" 
          modified="1,2020-06-15 16:32:20" isdirectory="Yes" size="4096" 
          prettyName="/sites" iconPath="img/files/dir.gif" mime-type="" 
          share-name="sites" parent="439541447604990017">124561914478016686</path>
    <path name="/" path="439541447604990017" title="" comments="" 
          draft="0" review="" finalDraft="0" permissions="8191" user="0" 
          modified="" isdirectory="Yes" size="" prettyName="/System Drive" 
          iconPath="img/files/dir.gif" mime-type="" share-name="System Drive" 
          parent="">439541447604990017</path>
  </result>
</response>

listRootContents

List the merged contents of all root drives.

Parameter	Type	Description
sessionID	string	Session ID for authentication
includeMetaData	boolean	Include metadata in response
n / results	integer	Number of items to return
offset	integer	Starting position
sort	csv	Column:asc or column:desc pairs
restrict	string	Restrict to "files", "dirs", or "both"

Returns: A result element containing path elements.

Example Request:

<?xml version="1.0"?>
<request command="listRootContents" sessionID="..."/>

Example Response:

<?xml version="1.0"?>
<response status="ok">
  <result>
    <path>107948987516620055</path>
    <path>109476079367542263</path>
    <path>116943545315178810</path>
  </result>
</response>

Share one or more documents or folders with one or more users or groups.

Parameter	Type	Description
sessionID	string	Session ID for authentication
subject	string	Email message subject
message	string	Email message body
other_emails	csv	Comma-separated list of email addresses
access	integer	Access permissions integer
end_date	date	Expiry date for access
ids	csv	WebPal user IDs
groups	csv	Group names to share with
attachments	csv	'pdf', 'thumbnail', 'original'
paths	csv	List of file/folder paths to share
pretty	boolean	Interpret paths as symbolic

Returns: An empty result element.

Example Request:

<?xml version="1.0"?>
<request command="share" sessionID="..." ids="5,80" access="529" 
         message="test" subject="test" paths="186039282571318132"/>

Example Response:

<?xml version="1.0"?>
<response status="ok">
  <result/>
</response>

createGroupShare

Create a share to a group without sending an email.

Parameter	Type	Description
sessionID	string	Session ID for authentication
path	string	File/folder ID or symbolic path
pretty	boolean	If true, interpret path as symbolic
group	string	The name of the group
permissions	integer	Permissions integer (default: view and download)
expiry	date	Expiration date (YYYY-MM-DD HH:MM:SS)

Returns: A result element containing a share element with share details.

Example Request:

<?xml version="1.0"?>
<request command="createGroupShare" sessionID="..." pretty="true" 
         path="/System Drive/test/document" group="share-test"/>

Example Response:

<?xml version="1.0"?>
<response status="ok">
  <result>
    <share id="628" name="" from="1" to="" group="2" version="" 
           permissions="529" path="/System Drive/test/document" 
           file_id="103717787211901174" type="Email" expiry="" 
           expiry_formatted="" date_recorded="2020-06-16 10:47:06"/>
  </result>
</response>

createSystemShare

Create a system share (root drive) for a user. Logged-in user must be admin if creating share for another user.

Parameter	Type	Description
sessionID	string	Session ID for authentication
path	string	Folder ID or symbolic path
pretty	boolean	If true, interpret path as symbolic
name	string	Display name for the system share
login	string	User login
user_id	string	User ID (alternative to login)
permissions	integer	Permissions for the share
create	boolean	Create path if it doesn't exist

Returns: A result element containing a share element with share details.

Example Request:

<?xml version="1.0"?>
<request command="createSystemShare" sessionID="..." user_id="377" 
         path="/System Drive/test" pretty="true" name="My New Drive"/>

Example Response:

<?xml version="1.0"?>
<response status="ok">
  <result>
    <share id="630" name="My New Drive" from="" to="377" group="" version="" 
           permissions="8191" path="/System Drive/test" 
           file_id="151037544713428608" type="System" expiry="" 
           expiry_formatted="" date_recorded="2020-06-16 11:10:30"/>
  </result>
</response>

permissions

Return the permissions integer for the logged-in user or a specified user for a document or folder. Only admins can check permissions for other users.

Parameter	Type	Description
sessionID	string	Session ID for authentication
path	string	File/folder ID or symbolic path
pretty	boolean	If true, interpret path as symbolic
login	string	User login to check permissions for

Returns: A result element with a permissions attribute.

Example Request:

<?xml version="1.0"?>
<request command="permissions" sessionID="..." path="/System Drive" pretty="true"/>

Example Response:

<?xml version="1.0"?>
<response status="ok">
  <result permissions="8191" path="439541447604990017"/>
</response>

userShares

Display the shares or shared files for a user. Select user by ID or login. Only admins can view other users' shares.

Parameter	Type	Description
sessionID	string	Session ID for authentication
user_id	string	User ID
login	string	User login (or email if configured)
result_type	string	If "files", show shared files instead of shares
type	string	"system" for system shares only, "user" for user shares only

Returns: A result element containing file or share elements.

Example Request:

<?xml version="1.0"?>
<request command="userShares" sessionID="..." login="permissions-user-1" type="user"/>

Example Response:

<?xml version="1.0"?>
<response status="ok">
  <result __exists="yes">
    <share id="100" name="" from="34" to="33" group="" version="1" 
           permissions="16" path="/System Drive/share-root/report.txt" 
           file_id="113032034015986555" type="Email" expiry="" 
           expiry_formatted="" date_recorded="2020-04-14 20:22:48"/>
  </result>
</response>

User Management

listUsers

Query WebPal users with optional filtering and paging.

Parameter	Type	Description
sessionID	string	Session ID for authentication
n / results	integer	Number of results to return
offset	integer	Starting position
sort	csv	Column:asc or column:desc pairs
search	string	Substring matched against login, name, email, or groups
key<n>	string	Custom profile fields (installation-specific)

Returns: A result element with pagination attributes and Result elements for each user.

Example Request:

<?xml version="1.0"?>
<request command="listUsers" sessionID="..." rows="10" page="1"/>

Example Response:

<?xml version="1.0"?>
<response status="ok">
  <result totalResultsAvailable="121" totalResultsReturned="10" firstResultPosition="0">
    <Result id="356" login="user@example.com" name="Free Trial" 
            email="user@example.com" role="user" lastName="Trial" 
            firstName="Free" groups="palomino" date_created="2020-06-11 08:53:00"/>
  </result>
</response>

userInfo

Return detailed information about a specific user.

Parameter	Type	Description
sessionID	string	Session ID for authentication
user_id	string	User ID
login	string	User login (or email if configured)

Returns: A result element with __exists attribute and user details if found.

Example Request:

<?xml version="1.0"?>
<request command="userInfo" sessionID="..." user_id="380"/>

Example Response:

<?xml version="1.0"?>
<response status="ok">
  <result __exists="yes" id="380" login="testuser" name="" 
          email="test@example.com" role="user" lastName="" firstName="" 
          groups="" date_created="2020-06-16 11:14:00" displayName="testuser"/>
</response>

userExists

Check if an email or login exists in WebPal. Exactly one of login or email must be provided.

Parameter	Type	Description
sessionID	string	Session ID for authentication
login	string	Login to check
email	string	Email to check

Returns: A result element with exists attribute ("yes" or "no").

Example Request:

<?xml version="1.0"?>
<request command="userExists" sessionID="..." email="someone@example.com"/>

Example Response:

<?xml version="1.0"?>
<response status="ok">
  <result requestEmail="someone@example.com" exists="yes"/>
</response>

noMatchingUser

Check if an email or login exists in WebPal (inverse of userExists). If both are provided, email is checked.

Parameter	Type	Description
sessionID	string	Session ID for authentication
login	string	Login to check
email	string	Email to check

Returns: A result element with match attribute ("yes" or "no").

Example Request:

<?xml version="1.0"?>
<request command="noMatchingUser" sessionID="..." email="newuser@example.com"/>

Example Response:

<?xml version="1.0"?>
<response status="ok">
  <result requestEmail="newuser@example.com" match="yes"/>
</response>

userAddGroups

Add a user to one or more groups.

Parameter	Type	Description
sessionID	string	Session ID for authentication
user-id	string	Internal user ID
groupNames	string	Comma-separated list of group names

Returns: A result element with user info and group elements for each group.

Example Request:

<?xml version="1.0"?>
<request command="userAddGroups" sessionID="..." user-id="5" 
         groupNames="share-test, test-group"/>

Example Response:

<?xml version="1.0"?>
<response status="ok">
  <result id="5" login="test-user" name="Test User" 
          email="test.user@example.com" role="user" lastName="User" 
          firstName="Test" groups="share-test, test-group" 
          date_created="2019-12-27 13:58:00" displayName="Test User">
    <group name="share-test"/>
    <group name="test-group"/>
  </result>
</response>

userRemoveGroups

Remove a user from one or more groups.

Parameter	Type	Description
sessionID	string	Session ID for authentication
user-id	string	Internal user ID
groupNames	string	Comma-separated list of group names

Returns: A result element with user info and remaining groups.

Example Request:

<?xml version="1.0"?>
<request command="userRemoveGroups" sessionID="..." user-id="5" 
         groupNames="share-test, test-group"/>

Example Response:

<?xml version="1.0"?>
<response status="ok">
  <result id="5" login="test-user" name="Test User" 
          email="test.user@example.com" role="user" lastName="User" 
          firstName="Test" groups="" date_created="2019-12-27 13:58:00" 
          displayName="Test User"/>
</response>

fetchUserProfile

Retrieve user profile data for the logged-in user or an arbitrary user (admin only).

Parameter	Type	Description
sessionID	string	Session ID for authentication
user_id	string	User ID (optional, defaults to logged-in user)

Returns: A result element with user_id attribute and value elements for each profile key/value pair.

Example Request:

<?xml version="1.0"?>
<request command="fetchUserProfile" sessionID="..."/>

Example Response:

<?xml version="1.0"?>
<response status="ok">
  <result user_id="340">
    <value key="Organization" value="A Company"/>
    <value key="Job Title" value="CEO"/>
  </result>
</response>

updateUserProfile

Update user profile data for the logged-in user or an arbitrary user (admin only). Keys and values are specified as set elements.

Parameter	Type	Description
sessionID	string	Session ID for authentication
user_id	string	User ID (optional, defaults to logged-in user)

Returns: A result element with updated profile values.

Example Request:

<?xml version="1.0"?>
<request command="updateUserProfile" sessionID="...">
  <set key="Organization" value="A Company"/>
  <set key="Job Title" value="CEO"/>
</request>

Example Response:

<?xml version="1.0"?>
<response status="ok">
  <result user_id="340">
    <value key="Organization" value="A Company"/>
    <value key="Job Title" value="CEO"/>
  </result>
</response>

userFile

Returns the pretty path name that would be used by a specified user for a given file.

Parameter	Type	Description
sessionID	string	Session ID for authentication
user	string	Login for the user
path	string	File ID or symbolic path
pretty	boolean	If true, interpret path as symbolic

Returns: A result element with prettyName attribute and path element.

Example Request:

<?xml version="1.0"?>
<request command="userFile" sessionID="..." path="109476079367542263" user="user1"/>

Example Response:

<?xml version="1.0"?>
<response status="ok">
  <result prettyName="/System Drive/report1.csv">
    <path>109476079367542263</path>
  </result>
</response>

Group Management

listGroups

Return all groups in the system.

Parameter	Type	Description
sessionID	string	Session ID for authentication

Returns: A result element with pagination attributes and Result elements for each group.

Example Request:

<?xml version="1.0"?>
<request command="listGroups" sessionID="..."/>

Example Response:

<?xml version="1.0"?>
<response status="ok">
  <result totalResultsAvailable="2" totalResultsReturned="2" firstResultPosition="0">
    <Result id="1" name="palomino" description="Super users" 
            lastmodified="2019-01-27 01:39:55" numofusers="34"/>
    <Result id="2" name="share-test" description="Testing shares" 
            lastmodified="2019-12-27 19:51:33" numofusers="2"/>
  </result>
</response>

lookupGroup

Check if a named group exists and return information about it.

Parameter	Type	Description
sessionID	string	Session ID for authentication
name	string	The name of the group

Returns: A result element with __exists attribute and group details if found.

Example Request:

<?xml version="1.0"?>
<request command="lookupGroup" sessionID="..." name="share-test-group"/>

Example Response:

<?xml version="1.0"?>
<response status="ok">
  <result __exists="yes" id="105" description="For testing" 
          name="share-test-group" shareCount="110" shareGroup="no"/>
</response>

Metadata & Search

metaData

Return the metadata for a file or folder.

Parameter	Type	Description
sessionID	string	Session ID for authentication
path	string	File/folder ID or symbolic path
pretty	boolean	If true, interpret path as symbolic

Returns: A result element containing elements for each file property.

Example Request:

<?xml version="1.0"?>
<request command="metaData" sessionID="..." path="822767450189213657"/>

Example Response:

<?xml version="1.0"?>
<response status="ok">
  <result>
    <name>zzz.wdoc</name>
    <path>822767450189213657</path>
    <title>Document Title</title>
    <comments>Document comments</comments>
    <draft>no</draft>
    <review>no</review>
    <finalDraft>yes</finalDraft>
    <permissions>1975</permissions>
    <user>5</user>
    <modified>5,2020-06-08 19:28:16</modified>
    <isdirectory>No</isdirectory>
    <size>12</size>
    <prettyName>/Documents/zzz.wdoc</prettyName>
  </result>
  <iconPath>img/files/webpal-icon-word-small.png</iconPath>
</response>

setMetaData

Change metadata fields for a document or folder.

Parameter	Type	Description
sessionID	string	Session ID for authentication
path	string	File/folder ID or symbolic path
pretty	boolean	If true, interpret path as symbolic
title	string	New title
comments	string	New comments
review	boolean	Needs review status
draft	boolean	Draft status
finalDraft	boolean	Final draft status

Returns: A result element containing updated file properties.

Example Request:

<?xml version="1.0"?>
<request command="setMetaData" sessionID="..." path="822767450189213657" 
         title="New Title" comments="New comments" finalDraft="yes"/>

Example Response:

<?xml version="1.0"?>
<response status="ok">
  <result>
    <name>zzz.wdoc</name>
    <path>822767450189213657</path>
    <title>New Title</title>
    <comments>New comments</comments>
    <draft>no</draft>
    <review>no</review>
    <finalDraft>yes</finalDraft>
    <permissions>1975</permissions>
    <user>5</user>
    <modified>5,2020-06-08 19:28:16</modified>
    <isdirectory>No</isdirectory>
    <size>12</size>
    <prettyName>/Documents/zzz.wdoc</prettyName>
  </result>
  <iconPath>img/files/webpal-icon-word-small.png</iconPath>
</response>

index

Add a file to the full-text search index.

Parameter	Type	Description
sessionID	string	Session ID for authentication
path	string	File ID or symbolic path
pretty	boolean	If true, interpret path as symbolic

Returns: A result element with indexed attribute.

Example Request:

<?xml version="1.0"?>
<request command="index" sessionID="..." path="213412696680068522"/>

Example Response:

<?xml version="1.0"?>
<response status="ok">
  <result indexed="ok"/>
</response>

Activity & Monitoring

listActivity

Return a portion of the activity log with optional filtering and paging.

Parameter	Type	Description
sessionID	string	Session ID for authentication
n / results	integer	Number of results to return
offset	integer	Starting position
sort	csv	Column:asc or column:desc pairs
type	string	Type of object to return
dirs	boolean	Return only folder activity
files	boolean	Return only file activity

Returns: A result element with pagination attributes and Result elements for each activity record.

Example Request:

<?xml version="1.0"?>
<request command="listActivity" sessionID="..." rows="2" page="2"/>

Example Response:

<?xml version="1.0"?>
<response status="ok">
  <result totalResultsAvailable="67537" totalResultsReturned="2" firstResultPosition="2">
    <Result id="3" user_id="1" time_inserted="2019-01-27 01:46:28" 
            action="Uploaded" from="/System Drive/file.txt" 
            to="/System Drive" description="" program_mode="ui" 
            real_user_id="" session_id="" full_name="bryan (George Hoover)" 
            login="bryan" firstname="George" lastname="Hoover" 
            pretty_action="Uploaded Document"/>
  </result>
</response>

recentActivity

Return recent activity for the logged-in user (files that have changed, been added, or deleted).

Parameter	Type	Description
sessionID	string	Session ID for authentication
max-records	integer	Maximum number of records (default: 6)
max-days	integer	Maximum days to go back (default: 18)

Returns: A result element containing path elements with file information.

Example Request:

<?xml version="1.0"?>
<request command="recentActivity" sessionID="..." max-records="5"/>

Example Response:

<?xml version="1.0"?>
<response status="ok">
  <result>
    <path file_id="122941992367239941" user="1" action="uploaded" 
          from_dir="" to_dir="151037544713428608" to_user="" description="" 
          real_user_id="" date_recorded="2020-06-16 15:14:43" 
          sort_value="2020-06-16 11:14:43"/>
  </result>
</response>

Path Utilities

getPrettyName

Returns the pretty (symbolic) name for a file or folder path.

Parameter	Type	Description
sessionID	string	Session ID for authentication
path	string	File/folder ID or symbolic path
pretty	boolean	If true, interpret path as symbolic

Returns: A result element with prettyName and path attributes.

Example Request:

<?xml version="1.0"?>
<request command="getPrettyName" sessionID="..." path="109476079367542263"/>

Example Response:

<?xml version="1.0"?>
<response status="ok">
  <result path="109476079367542263" prettyName="/System Drive/report1.csv"/>
</response>

lookupPretty

Returns the document ID corresponding to a given pretty (symbolic) name.

Parameter	Type	Description
sessionID	string	Session ID for authentication
path	string	The pretty path to look up

Returns: A result element with a path attribute containing the ID.

Example Request:

<?xml version="1.0"?>
<request command="lookupPretty" sessionID="..." path="/System Drive"/>

Example Response:

<?xml version="1.0"?>
<response status="ok">
  <result path="439541447604990017"/>
</response>

Thumbnail & Image Operations

thumbnail

Return the contents of a document's thumbnail image.

Parameter	Type	Description
sessionID	string	Session ID for authentication
path	string	File ID or symbolic path
pretty	boolean	If true, interpret path as symbolic

Returns: The thumbnail image with appropriate MIME type.

Example Request:

<?xml version="1.0"?>
<request command="thumbnail" sessionID="..." pretty="true" 
         path="/sites/report2.txt"/>

thumbnailOrImage

Download the thumbnail if available, or if an image and no thumbnail exists, return the image itself.

Parameter	Type	Description
sessionID	string	Session ID for authentication
path	string	File ID or symbolic path
pretty	boolean	If true, interpret path as symbolic

Returns: The thumbnail or image with appropriate MIME type.

Example Request:

<?xml version="1.0"?>
<request command="thumbnailOrImage" sessionID="..." pretty="true" 
         path="/sites/image.jpg"/>

hasThumbnail

Check if a document has a thumbnail generated.

Parameter	Type	Description
sessionID	string	Session ID for authentication
path	string	File ID or symbolic path
pretty	boolean	If true, interpret path as symbolic

Returns: A result element with hasThumbnail attribute ("yes" or "no").

Example Request:

<?xml version="1.0"?>
<request command="hasThumbnail" sessionID="..." pretty="true" 
         path="/System Drive/report2.txt"/>

Example Response:

<?xml version="1.0"?>
<response status="ok">
  <result hasThumbnail="no"/>
</response>

generateThumbnails

Regenerate a thumbnail for a document, then return its contents.

Parameter	Type	Description
sessionID	string	Session ID for authentication
path	string	File ID or symbolic path
pretty	boolean	If true, interpret path as symbolic

Returns: The newly generated thumbnail image.

Example Request:

<?xml version="1.0"?>
<request command="generateThumbnails" sessionID="..." pretty="true" 
         path="/sites/document.pdf"/>

icon

Download the icon for a document type. If a name is given, the content disposition uses that filename.

Parameter	Type	Description
sessionID	string	Session ID for authentication
path	string	File ID or symbolic path
pretty	boolean	If true, interpret path as symbolic
name	string	Filename for content disposition header

Returns: The icon image file.

Example Request:

<?xml version="1.0"?>
<request command="icon" sessionID="..." pretty="true" 
         path="/Documentation/report.txt"/>

PDF Operations

pdf

Download a PDF version of a document. For documents that aren't PDFs, WebPal will convert them. Optionally apply watermarks or stamps.

Parameter	Type	Description
sessionID	string	Session ID for authentication
path	string	File ID or symbolic path
pretty	boolean	If true, interpret path as symbolic
watermark	string	Text of the watermark
watermark-position	string	One of: top, left, bottom, right, diagonal
watermark-font-name	string	Font name to use
watermark-font-size	integer	Font size
watermark-color	string	RGB as comma-separated (e.g., "255,0,0")
watermark-mode	string	One of: stamp, watermark

Returns: The PDF file with MIME type application/pdf.

Example Request:

<?xml version="1.0"?>
<request command="pdf" sessionID="..." pretty="true" 
         path="/System Drive/Report.pdf" watermark="Downloaded on 2020-06-12" 
         watermark-mode="stamp" watermark-position="diagonal" 
         watermark-font-size="30"/>

toPDF

Generate PDFs from URLs or uploaded files. If no destination is specified, download the first PDF.

Parameter	Type	Description
sessionID	string	Session ID for authentication
path	string	Folder path for generated PDFs (if pretty and create are true)
pretty	boolean	If true, path is symbolic
create	boolean	Create folder if it doesn't exist
dest	string	Destination folder (overrides path)
subdirectory	string	Name of subfolder to create in dest
fileName	string	Filename for download
urls	csv	Comma-separated list of URLs to convert
paper	string	Paper size (e.g., "Letter")
margins	csv	Margins (e.g., "1cm,1cm,1cm,1cm")
concatenate	boolean	Concatenate multiple PDFs into one
title	string	WebPal title for created documents
comments	string	WebPal comments for created documents

Returns: Either a downloaded PDF (application/pdf) or a result element with paths of newly created documents.

Example Request:

<?xml version="1.0"?>
<request command="toPDF" sessionID="..." urls="https://example.com"/>

CSV Operations

csv.appendRow

Add a row to the end of a CSV file. Assumes the CSV has column names in the first row.

Parameter	Type	Description
sessionID	string	Session ID for authentication
csv-file	string	CSV file ID or symbolic path
pretty	boolean	If true, interpret csv-file as symbolic

Row data is specified using form elements with name (column name) and value attributes.

Returns: A result element containing a path element with the updated file metadata.

Example Request:

<?xml version="1.0"?>
<request command="csv.appendRow" sessionID="..." csv-file="115393717311806343">
  <form name="col1" value="2020-07-03 18:33:08"/>
  <form name="col2" value="b"/>
  <form name="col3" value="c"/>
</request>

Example Response:

<?xml version="1.0"?>
<response status="ok">
  <result>
    <path name="file.csv" path="115393717311806343" title="" comments="" 
          draft="0" review="" finalDraft="0" permissions="8191" user="458" 
          modified="458,2020-07-03 14:26:05" isdirectory="No" size="57" 
          prettyName="/user1/file.csv" iconPath="img/files/file.gif" 
          mime-type="text/plain" version="4" 
          parent="834318401130303479">115393717311806343</path>
  </result>
</response>

Utility Commands

ping

Simple command that returns 'ok' to keep a session alive or verify it's still valid.

Parameter	Type	Description
sessionID	string	Session ID to verify

Returns: Status "ok" if session is valid, or an error if expired.

Example Request:

<?xml version="1.0"?>
<request command="ping" sessionID="..."/>

Example Response:

<?xml version="1.0"?>
<response status="ok"/>

introspect

Return all API commands with complete documentation including parameters and examples.

Parameter	Type	Description
sessionID	string	Session ID (optional for this command)

Returns: A response with a count attribute and command elements for each API command.

Example Request:

<?xml version="1.0"?>
<request command="introspect"/>

Example Response:

<?xml version="1.0"?>
<response count="87" status="ok">
  <command name="append">
    <comment>Append text to a document</comment>
    <parameter macro="true" type="standard-path" optional="yes">
      <name>path</name>
      <comment>The document to which to append text.</comment>
    </parameter>
    <!-- ... more parameters ... -->
  </command>
  <!-- ... more commands ... -->
</response>

viewerLink

Return file information including a viewer link for displaying the document in WebPal's viewer.

Parameter	Type	Description
sessionID	string	Session ID for authentication
path	string	File ID or symbolic path
pretty	boolean	If true, interpret path as symbolic
permanent	boolean	If true, the link is permanent

Returns: A result element containing a path element with full metadata and a link attribute.

Example Request:

<?xml version="1.0"?>
<request command="viewerLink" sessionID="..." path="822767450189213657"/>

Example Response:

<?xml version="1.0"?>
<response status="ok">
  <result>
    <path name="zzz.wdoc" path="822767450189213657" title="" comments="" 
          draft="0" review="" finalDraft="0" permissions="1975" user="5" 
          modified="5,2020-06-08 15:28:16" isdirectory="No" size="12" 
          prettyName="/Documents/test.wdoc" 
          iconPath="img/files/webpal-icon-word-small.png" 
          mime-type="text/plain" version="1" parent="414166113199212091" 
          link="http://dm.internal/viewer/pdfViewer?k=4xOvYYCYFUYWvkzezDczvR1DDM_mHTveSe8ceBen">822767450189213657</path>
  </result>
</response>

Need Complete Documentation?

Use the introspect command to get full API documentation including all commands and parameters:

<request command="introspect"/>

Introduction

Endpoint

Request Format

Response Format

Authentication

login

logout

Common Parameters

Paths and IDs

Boolean Parameters

Paging and Sorting

Authentication Commands

login

logout

resetPassword

File Operations

upload

download

append

copy

move

delete

rename

exists

fileInfo

fileCount

Folder Operations

createFolder

listDirectory

listRoots

listRootContents

Sharing & Permissions

share

createGroupShare

createSystemShare

permissions

userShares

User Management

listUsers

userInfo

userExists

noMatchingUser

userAddGroups

userRemoveGroups

fetchUserProfile

updateUserProfile

userFile

Group Management

listGroups

lookupGroup

Metadata & Search

metaData

setMetaData

index

Activity & Monitoring

listActivity

recentActivity

Path Utilities

getPrettyName

lookupPretty

Thumbnail & Image Operations

thumbnail

thumbnailOrImage

hasThumbnail

generateThumbnails

icon

PDF Operations

pdf

toPDF

CSV Operations

csv.appendRow

Utility Commands

ping

introspect

viewerLink

Need Complete Documentation?