|
 API v2 is still in development. We welcome suggestions and questions at api@pbwiki.com. Be sure to check out the PBwiki API mailing list. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| v2 API keys should be kept as secret as any other password. | ||
| Name | Value | Description |
| admin_key | *************************** | v2 API admin key |
| write_key | *************************** | v2 API write key |
| read_key | *************************** | v2 API read key |
Welcome to the PBwiki v2 API documentation!
Select an operation from the left menu to get started.
Key Concepts
PBwiki API access is available through two different mechanisms. First, you can use the API Keys available here to indicate your (or your program's) rights to connect to this wiki. Second, you can use your browser's session cookies to convey the appropriate rights.
When invoking an operation with your browser session, you will need to provide an additional input in order to prevent the possibilty of a Cross-Site Scripting compromise. The practical result of this is that malicious code on a non-PBwiki site won't know your session cookie value, so it won't be able to cause you to accidentally or unwittingly change your wiki. At the same time, there is no practical way for a third party to cause you to convey wiki content back to them without your active participation.
Our security model assumes that any JavaScript on your wiki will have been vetted by the wiki's administrator so it's not helpful to restrict it beyond our standard mechanisms for privilege isolation. Your wiki session is particular to this wiki and does not directly identify you without additional information which is not exposed anywhere. If through accident or malfeasance your session is compromised on one wiki that wiki session cannot be used to grant someone else privileges on another wiki on which you have a PBwiki account. We use the 'ws' cookie to identify your session and in turn to identify your user account but the reverse relation is not available programatically.
Welcome to the PBwiki v2 API documentation!
Select an operation from the left menu to get started.
Key Concepts
PBwiki API access is available through two different mechanisms. First, you can use the API Keys available here to indicate your (or your program's) rights to connect to this wiki. Second, you can use your browser's session cookies to convey the appropriate rights.
When invoking an operation with your browser session, you will need to provide an additional input in order to prevent the possibilty of a Cross-Site Scripting compromise. The practical result of this is that malicious code on a non-PBwiki site won't know your session cookie value, so it won't be able to cause you to accidentally or unwittingly change your wiki. At the same time, there is no practical way for a third party to cause you to convey wiki content back to them without your active participation.
Our security model assumes that any JavaScript on your wiki will have been vetted by the wiki's administrator so it's not helpful to restrict it beyond our standard mechanisms for privilege isolation. Your wiki session is particular to this wiki and does not directly identify you without additional information which is not exposed anywhere. If through accident or malfeasance your session is compromised on one wiki that wiki session cannot be used to grant someone else privileges on another wiki on which you have a PBwiki account. We use the 'ws' cookie to identify your session and in turn to identify your user account but the reverse relation is not available programatically.
PBwiki Delegated Authentication
This advanced feature is available by special arrangement with PBwiki.
Executive summary
- This enables Single Sign On (SSO) with your existing LDAP/ActiveDirectory installation.
- You'll need to run a few lines of code on a webserver that can talk to your LDAP/AD server.
- You will NOT need to open a hole in your firewall for PBwiki.
- Estimated time for you to get up and running: one day.
Implementation notes
PBwiki identifies users by email address. Traditionally, a user enters her email address and password on a wiki login page to get access to that wiki. At the same time, she'll be logged in as that user for all of PBwiki, including all wikis she's a member of listed at https://my.pbwiki.com/
PBwiki Delegated Authentication allows a designated email domain or set of email domains to be identified by a particular customer's own servers rather than via traditional email+password authentication. Rather than simply asserting that a particular browser should be allowed access to a particular wiki, PBwiki Delegated Authentication allows a customer server to make a verifiable assertion about the identity of a user. That user will then be logged in to the entirety of PBwiki, with the proper access to the wikis they are a member of. If there is no existing PBwiki account for the user in question, a PBwiki account is created automatically.
No information is directly transferred between the customer server and PBwiki or vice versa — all of the transaction is performed via the user's browser cookies and URL redirection.
In addition to the identity assertion, a properly configured customer server can assert that user's identity as well as their permission level on a particular wiki. This assertion is of course only possible for wikis which have been associated with that configuration. Contact your PBwiki sales rep for more information.
Definitions for this documentation
| Name | How transmitted | |
| {auth server} | URL | The web server (could be behind a firewall), listening for HTTPS or HTTP and able to talk to your LDAP/AD server e.g. https://auth-intranet.customer.com/login.aspx [You provide this URL to PBwiki] |
| {domain} | GET parameter | One of one or more email domains approved for delegation by PBwiki for your use. If your email address is kevin@customer.com, domain would be e.g. customer.com [You provide this info to PBwiki] |
| {shared secret} | Never transferred | A random string of characters provided to you by PBwiki for each of one or more authenication domains e.g. examplesharedsecret [PBwiki gives you this once] |
| {token} | GET parameter | One-time-use random token generated by PBwiki and used by the {auth server} to sign the user's credentials e.g. EXAMPLETOKEN |
| {email} | GET parameter | Email address for user. The domain part of the email address MUST match {domain} e.g. someuser@customer.com |
| {time} | GET parameter | Official PBwiki time in Unix epoch seconds e.g. 1231280609 |
| {secret cookie} | Browser cookie | One-time-use cookie related to but not identical to {token} and only visible to https://my.pbwiki.com/ e.g. ExampleSecret |
Test harness
When configuring your {auth server} it is helpful to verify the paramater passing and credentials signing mechanism independent of the particular back-office login you choose to implement. Use the test tool to confirm you get the correct results using the provided sample code.
PBwiki Delegated Authentication test tool: https://my.pbwiki.com/delegate/test
Example transaction
| Data flows | Description | Example URL | ||||||||||||||||||||||
 →  User to PBwiki | Begin request (via wiki login form) | https://eg.pbwiki.com/session/custom | ||||||||||||||||||||||
| → PBwiki to User | PBwiki sets our {secret cookie} cookie (which the {auth server} does not see) on the user's browser then redirects the user to your designated {auth server} after adding the appropriate URL parameters | https://auth-intranet.customer.com/login.aspx?token=EXAMPLETOKEN&time=1231280609 -or- https://auth-intranet.customer.com/login.aspx?token=EXAMPLETOKEN&time=1231280609&domain=customer.com&email=someuser%40customer.com&wiki=eg Required parameters:
Optional parameters:
| ||||||||||||||||||||||
→  User to {auth server} | User completes login at {auth server} | This could involve any number of steps (including zero) for the user as appropriate for your infrastructure and policies. Examples include Active Directory, LDAP, Kerberos, RSA/SecureID, etc. | ||||||||||||||||||||||
| → {auth server} to User | {auth server} determines the user's credentials, constructs signed URL, redirects user to PBwiki Important: the user is directed to https://my.pbwiki.com/ — not the wiki they are logging in to. The reason to not direct someone directly to the wiki is that PBwiki needs to use HTTPS end-to-end for the main identification phase. We do this to protect a user's identity by isolating credentials to a particular wiki - a compromise in one place cannot propagate elsewhere. We can't use HTTPS with wikis hosted on a custom domain because we don't have the SSL certificate for those other domains but we are guaranteed to have a proper certificate for my.pbwiki.com. After the credential is accepted a session cookie is granted on my.pbwiki.com. If a wiki and permission is specified by the incoming delegated authentication request you generate, we can redirect to the wiki with our standard session-granting URL parameter. That session parameter is sent over HTTPS for those wikis which can support it and standard HTTP for domained wikis. | https://my.pbwiki.com/?token=EXAMPLETOKEN&email=someuser%40customer.com&name=Your%20Name&domain=customer.com&valid_until=1231281209&signature=d699827945efd93430331f1dbbc860d696d0e149 -or- https://my.pbwiki.com/?token=EXAMPLETOKEN&email=someuser%40customer.com&name=Your%20Name&domain=customer.com&valid_until=1231281209&wiki=eg&perm=write&signature=d699827945efd93430331f1dbbc860d696d0e149 Required parameters:
Optional parameters:
Signature parameters:
| ||||||||||||||||||||||
| → User to PBwiki | Request completed, and on success user is forwarded to https://my.pbwiki.com/ or https://eg.pbwiki.com/ as appropriate. | PBwiki analyzes the {signature}, {shared secret}, {domain}, {secret cookie}, {valid_until}, {wiki} and {perm} values to approve or deny the assertion made by {auth server} |
Sample code (PHP for now, more examples coming soon)
This trivial PHP script constructs a properly signed Delegated Authentication reply which PBwiki can validate.
<?php
// This file is part of the PBwiki Delgated Authentication documentation set.
// This script shows the simplest possible PHP code for signing a Delgated Authentication credential.
// It should be clear that this is a trivial example, and should never be used in actual production.
// @version $Id: delegated_auth_simplest_possible.php 7330 2008-11-08 03:28:00Z dustball $
$domain = 'tdemo.net'; // your domain here
$secret = 'SharedSecret'; // your shared secret from PBwiki
/* $email and $name would come from your LDAP database, for example */
$email = rawurlencode('useremail@' . $domain); // this will be in the url so need to urlencode
$name = rawurlencode('Made-up Test User'); // this will be in the url so need to urlencode
$expires = time() + 3600; // one hour, for example - time() is UNIX epoch seconds
$token = $_GET['token']; // the one-time token from PBwiki
$signature = sha1($secret . $token . $expires); // in PHP sha1() returns e.g. d5a9f719983240ab232f069a12fd52c8f3750f8c
$return_to = "https://my.pbwiki.com/?email=$email&name=$name&domain=$domain&valid_until=$expires&token=$token&signature=$signature";
header("Location: $return_to");
print "Done!";
?>
This is an example of the code which should run on the {auth server} machine. It verifies a user's identity and permissions according to your organization's policies and then constructs a secure PBwiki URL which PBwiki can validate.
<?php
// This file is part of the PBwiki Delgated Authentication documentation set.
// @version $Id: delegated_auth_sample_code.php 7330 2008-11-08 03:28:00Z dustball $
$auth_domain = 'tdemo.net'; // your domain, as approved by PBwiki
$our_shared_domain_secret = 'SharedSecret'; // your domain's shared secret, provided by PBwiki
$valid_seconds = 24 * 60 * 60; // one day (you should choose a reasonable value for your policies).
$header = <<<EOT
<head><title>Demo login page</title><style>body { background-color: #ccc; font-family:Courier,fixed-width; }
h1 { font-style: italic; margin-left:200px; }
#loginform, #forward { background-color: #fff; padding:20px; width:500px; border:5px solid #888; margin-left:200px; }
#info { font-size: 12px; } a { font-size:90%; }
</style>
</head><h1>Log in at $auth_domain</h1>
EOT;
$in_token = stripslashes($_REQUEST['token']);
$in_email = stripslashes($_REQUEST['email']);
$in_password = stripslashes($_POST['password']);
// generally speaking we return credentials to my.pbwiki.com - that's where the secure user session lives.
if (!$return_to_url = stripslashes($_REQUEST['pbwikidomain'])) {
$return_to_url = 'https://my.pbwiki.com/';
}
$incept_url = "https://my.pbwiki.com/delegate/gettoken?domain=$auth_domain";
if (!$in_token) {
print "Sorry, didn't get a token for this domain. Try again please.<br>";
print "<a href=\"$incept_url\">Click here to begin login</a>";
exit;
}
if ($_REQUEST['badtoken']) {
$in_token.= 'FAIL';
}
if ($in_password) {
$u_info = user_info_for_email_and_password_in_domain($in_email, $in_password, $auth_domain);
// getting to this point implies login success for this trivial example.
// this is reasonable if your clock is in sync with NTP servers
$valid_until = $valid_seconds + time();
$url = $return_to_url;
$url = util_add_url_arguments($url, array(
'email' => $in_email,
'name' => $u_info['name'],
'domain' => $auth_domain,
'valid_until' => $valid_until,
'token' => $in_token,
));
if ($u_info['wiki']) {
// we are asserting the user's identity (via the 'email' and 'name' fields) as well as their permission
// on a particular wiki we control
$url = util_add_url_arguments($url, array(
'wiki' => $u_info['wiki'],
'perm' => $u_info['perm'],
));
$signature = sha1($our_shared_domain_secret . $_REQUEST['token'] . $valid_until . $u_info['wiki'] . $u_info['perm']);
} else {
// we are asserting only the user's identity (via the 'email' and 'name' fields)
$signature = sha1($our_shared_domain_secret . $_REQUEST['token'] . $valid_until);
}
if ($_REQUEST['badsha1']) {
$signature.= 'FAIL';
}
$url = util_add_url_argument($url, 'signature', $signature);
// done, success!
print $header;
$secs = 5;
$displayurl = $url;
$displayurl = str_replace('?', '?<br>', $displayurl);
$displayurl = str_replace('&', '&<br>', $displayurl);
print <<<EOT
<div id="forward">
OK, forwarding you to this url:<br>
<ul><li><a href="$url">$displayurl</a></li></ul><br>
Normally that would be instant but this is an example. Redirecting in $secs seconds.
</div>
<meta http-equiv="refresh" content="$secs;URL=$url" >
EOT;
exit;
}
if ($auth_domain == 'tdemo.net') {
$more_info = '<hr>This is a sample transaction using the PBwiki delegated authentication test harness. ';
if ($_SERVER['HTTP_HOST'] == 'login.tdemo.net') {
$more_info.= '<hr>The code is running on a Dreamhost virtual server but normally would be installed';
$more_info.= ' on a server within your organization. ';
$more_info.= 'See <a href="http://pbwiki.com/api_v2/#Delegated_Auth">http://pbwiki.com/api_v2/#Delegated_Auth</a>';
$more_info . -' to get the latest version of this sample code. <hr>';
}
$more_info.= 'We have received some info from the PBwiki server and will send a sample signature and ';
$more_info.= 'identification back for validation. You can just click "Proceed" to test the system.';
$pwd_hint = 'example';
}
// since we didn't make it all the way though pushing the user back to PBwiki, better draw that login form
$login_form = <<<EOT
<div id="loginform">
<form method=post>
email<input type="text" name="email" value="$in_email"><br>
password<input type="text" name="password" value="$pwd_hint"><br>
{token}<input type="text" name="token" value="$in_token" ><br>
{pbwikidomain}<input type="text" name="pbwikidomain" value="$return_to_url" ><br>
<input type="checkbox" name="badtoken"> simulate an invalid token<br/>
<input type="checkbox" name="badsha1"> simulate an invalid signature<br/>
<input type=submit value="Proceed">
<div id="info">$more_info</div>
</form>
EOT;
print $header;
print $login_form;
// this is where you would call out to an LDAP or Active Directory server to decide what permissions the user gets.
function user_info_for_email_and_password_in_domain($email, $password, $auth_domain) {
$our_wiki = 'eg'; //could be more than one wiki, of course.
$known_users = array(
"exampleuser@$auth_domain" => array(
'pass' => 'example',
'name' => 'Some Example User',
'wiki' => $our_wiki,
'perm' => 'read', //could be one of {read, write, edit, admin}
) ,
);
$u_rec = $known_users[$email];
if (!$u_rec) {
print 'Unknown user :' + $email;
exit;
}
if ($u_rec['pass'] != $password) {
print 'Bad password for user:' + $email;
exit;
}
return $u_rec;
}
// trivial functions - just tack on more GET parameters to a URL
function util_add_url_arguments($url, $kvs) {
foreach($kvs as $k => $v) {
$url = util_add_url_argument($url, $k, $v);
}
return $url;
}
function util_add_url_argument($url, $k, $v) {
if (preg_match('/\?/', $url)) {
$url.= '&';
} else {
$url.= '?';
}
$url.= rawurlencode($k) . '=' . rawurlencode($v);
return $url;
}
?>
Does not change wiki state
Example invocations:
http://{wiki}.pbwiki.com/api_v2/op/GetBundle/_type/jsontext/read_key/OBVIOUS-FAKE-KEY
http://{wiki}.pbwiki.com/api_v2/?op=GetBundle&_type=jsontext&read_key=OBVIOUS-FAKE-KEY
Your wiki's API documentation includes examples for curl and wget as well as runnable examples in PHP.
| Permanent cachability inputs [?] | ||
| Name | Type | Description |
| foldertime | epoch seconds | Last time any folder was added/deleted or a page was moved into or out of a folder |
| pagetime | epoch seconds | Last time any page was created/deleted/renamed/edited |
| tagtime | epoch seconds | Last time any page tag was added/deleted |
| filetime | epoch seconds | Last time any file was uploaded/delted/renamed |
| Required outputs | ||
| Name | Type | Description |
| bundle | array | Array which lists pages, files, tags and folders for the wiki |
Required inputs: none
Optional inputs: none
| Notes |
| This method is used internally by PBwiki for the auto-complete search function. It returns a (sometimes large) payload of data which reflects a fairly complete picture of the state of the wiki, including the list of pages, list of attached files, and tags. This is overkill for most operations, and should be used sparingly. |
Required auth level(s): page read write edit mod admin
Does not change wiki state
Example invocations:
http://{wiki}.pbwiki.com/api_v2/op/GetObjects/_type/jsontext/read_key/OBVIOUS-FAKE-KEY/folder/Some+Folder
http://{wiki}.pbwiki.com/api_v2/?op=GetObjects&_type=jsontext&read_key=OBVIOUS-FAKE-KEY&folder=Some+Folder
Your wiki's API documentation includes examples for curl and wget as well as runnable examples in PHP.
| Required inputs | ||
| Name | Type | Description |
| folder | string | Folder name |
| Optional inputs | ||
| Name | Type | Description |
| after | string | Specifies which record you last saw in a previous call in descending order, used for paging. If the sortby parameter is used, this will specify a value for that field. If not, this will specify a value for the name field. |
| after_object_type | string | What type of object the 'after' field is specifying. Either 'file' or 'page'. |
| before | string | Specifies which record you last saw in a previous call in ascending order, used for paging. If the sortby parameter is used, this will specify a value for that field. If not, this will specify a value for the name field. |
| before_object_type | string | What type of object the 'before' field is specifying. Either 'file' or 'page'. |
| count | int | Maximum number of records to return |
| filter | string | String to filter name by |
| folder | string | Folder name |
| offset | int | Number of records to skip |
| reverse | bool | Whether to reverse the order of the sorting |
| sortby | string | Which field to sort records by |
| verbose | bool | Whether to include metadata about each page or only return an array of names. Default is true. |
| type | string | What type of objects should be returned. Ether 'file', 'page' or 'both'. Default is 'both' |
| Permanent cachability inputs [?] | ||
| Name | Type | Description |
| filetime | epoch seconds | Last time any file was uploaded/delted/renamed |
| foldertime | epoch seconds | Last time any folder was added/deleted or a page was moved into or out of a folder |
| pagetime | epoch seconds | Last time any page was created/deleted/renamed/edited |
| permtime | epoch seconds | Last time folder or page security was changed |
| Required outputs | ||
| Name | Type | Description |
| objects | array | A list of files and pages in the wiki |
Required auth level(s): page read write edit mod admin
Does not change wiki state
Example invocations:
http://{wiki}.pbwiki.com/api_v2/op/GetOps/_type/jsontext/admin_key/OBVIOUS-FAKE-KEY
http://{wiki}.pbwiki.com/api_v2/?op=GetOps&_type=jsontext&admin_key=OBVIOUS-FAKE-KEY
Your wiki's API documentation includes examples for curl and wget as well as runnable examples in PHP.
| Required outputs | ||
| Name | Type | Description |
| ops | array | List available operations in the PBwiki v2 API |
Required inputs: none
Optional inputs: none
Permanent cachability inputs: n/a
Required auth level(s):
Does not change wiki state
Example invocations:
http://{wiki}.pbwiki.com/api_v2/op/Help/help/GetPage/_type/jsontext/admin_key/OBVIOUS-FAKE-KEY
http://{wiki}.pbwiki.com/api_v2/?op=Help&help=GetPage&_type=jsontext&admin_key=OBVIOUS-FAKE-KEY
Your wiki's API documentation includes examples for curl and wget as well as runnable examples in PHP.
| Required inputs | ||
| Name | Type | Description |
| help | string | op name to be described |
| Required outputs | ||
| Name | Type | Description |
| inputs | array | List of required inputs for specified method |
| outputs | array | List of required outputs for specified method |
| inputs_optional | array | List of optional inputs for specified method |
Optional inputs: none
Permanent cachability inputs: n/a
Required auth level(s):
Does not change wiki state
Example invocations:
http://{wiki}.pbwiki.com/api_v2/op/IsHiringEngineers/_type/jsontext/admin_key/OBVIOUS-FAKE-KEY
http://{wiki}.pbwiki.com/api_v2/?op=IsHiringEngineers&_type=jsontext&admin_key=OBVIOUS-FAKE-KEY
Your wiki's API documentation includes examples for curl and wget as well as runnable examples in PHP.
| Required outputs | ||
| Name | Type | Description |
| nowhiring | bool | Whether or not PBwiki is currently hiring Engineers |
Required inputs: none
Optional inputs: none
Permanent cachability inputs: n/a
Required auth level(s):
Does not change wiki state
Example invocations:
http://{wiki}.pbwiki.com/api_v2/op/Ping/_type/jsontext/admin_key/OBVIOUS-FAKE-KEY
http://{wiki}.pbwiki.com/api_v2/?op=Ping&_type=jsontext&admin_key=OBVIOUS-FAKE-KEY
Your wiki's API documentation includes examples for curl and wget as well as runnable examples in PHP.
| Required outputs | ||
| Name | Type | Description |
| time | epoch seconds | Official PBwiki time (seconds since Jan 1 1970 00:00:00 UTC ± ~1 sec) |
| ip | string | IP address of request originator |
| permission | string | Permission level as established by the credentials provided to the API |
Required inputs: none
Optional inputs: none
Permanent cachability inputs: n/a
Required auth level(s):
Does not change wiki state
Unimplemented. This is a proposed future component of the v2 API.Does not change wiki state
Unimplemented. This is a proposed future component of the v2 API.Changes wiki state. Updates 'filetime', 'file data'
| Required inputs | ||
| Name | Type | Description |
| file | string | File to delete |
| Anti-XSS inputs -- required unless using an API key [?] | ||
| Name | Type | Description |
| ws | string | Wiki session cookie value i.e. get_cookie("ws") |
| Optional inputs | ||
| Name | Type | Description |
| revision | int | Revision to delete |
| Required outputs | ||
| Name | Type | Description |
| success | bool | Whether the operation completed successfully |
Permanent cachability inputs: n/a
Required auth level(s): page read write edit mod admin
Does not change wiki state
Example invocations:
http://{wiki}.pbwiki.com/api_v2/op/GetFile/_type/jsontext/read_key/OBVIOUS-FAKE-KEY/filename/SOMEVALUE
http://{wiki}.pbwiki.com/api_v2/?op=GetFile&_type=jsontext&read_key=OBVIOUS-FAKE-KEY&filename=SOMEVALUE
Your wiki's API documentation includes examples for curl and wget as well as runnable examples in PHP.
| Required inputs | ||
| Name | Type | Description |
| filename | string | File name |
Optional inputs: none
Permanent cachability inputs: n/a
Required outputs: none
Required auth level(s): page read write edit mod admin
Does not change wiki state
Example invocations:
http://{wiki}.pbwiki.com/api_v2/op/GetFileRevisions/_type/jsontext/read_key/OBVIOUS-FAKE-KEY/file/SOMEVALUE
http://{wiki}.pbwiki.com/api_v2/?op=GetFileRevisions&_type=jsontext&read_key=OBVIOUS-FAKE-KEY&file=SOMEVALUE
Your wiki's API documentation includes examples for curl and wget as well as runnable examples in PHP.
| Required inputs | ||
| Name | Type | Description |
| file | string | File name |
| Optional inputs | ||
| Name | Type | Description |
| count | int | Maximum number of records to return |
| file | string | File name |
| offset | int | Number of records to skip |
| reverse | bool | Whether to reverse the order of the sorting |
| sortby | string | Which field to sort records by |
| verbose | bool | Whether to include metadata about each revision or only return an array of times. Default is false. |
| Permanent cachability inputs [?] | ||
| Name | Type | Description |
| filetime | epoch seconds | Last time any file was uploaded/delted/renamed |
| Required outputs | ||
| Name | Type | Description |
| revisions | array|false | Array of epoch seconds revisions for page (or false if file does not exist) |
Required auth level(s): page read write edit mod admin
Does not change wiki state
Example invocations:
http://{wiki}.pbwiki.com/api_v2/op/GetFiles/_type/jsontext/admin_key/OBVIOUS-FAKE-KEY
http://{wiki}.pbwiki.com/api_v2/?op=GetFiles&_type=jsontext&admin_key=OBVIOUS-FAKE-KEY
Your wiki's API documentation includes examples for curl and wget as well as runnable examples in PHP.
| Optional inputs | ||
| Name | Type | Description |
| after | string | Specifies which record you last saw in a previous call in descending order, used for paging. If the sortby parameter is used, this will specify a value for that field. If not, this will specify a value for the name field. |
| before | string | Specifies which record you last saw in a previous call in ascending order, used for paging. If the sortby parameter is used, this will specify a value for that field. If not, this will specify a value for the name field. |
| count | int | Maximum number of records to return |
| filter | string | String to filter name by |
| folder | string | Folder name |
| offset | int | Number of records to skip |
| reverse | bool | Whether to reverse the order of the sorting |
| sortby | string | Which field to sort records by |
| verbose | bool | Whether to include metadata about each page or only return an array of names. Default is true. |
| Permanent cachability inputs [?] | ||
| Name | Type | Description |
| filetime | epoch seconds | Last time any file was uploaded/delted/renamed |
| foldertime | epoch seconds | Last time any folder was added/deleted or a page was moved into or out of a folder |
| permtime | epoch seconds | Last time folder or page security was changed |
| Required outputs | ||
| Name | Type | Description |
| files | array | List of files accessible to the user |
Required inputs: none
Required auth level(s):
Does not change wiki state
Example invocations:
http://{wiki}.pbwiki.com/api_v2/op/GetStorageInfo/_type/jsontext/admin_key/OBVIOUS-FAKE-KEY
http://{wiki}.pbwiki.com/api_v2/?op=GetStorageInfo&_type=jsontext&admin_key=OBVIOUS-FAKE-KEY
Your wiki's API documentation includes examples for curl and wget as well as runnable examples in PHP.
| Required outputs | ||
| Name | Type | Description |
| available | int|float | Available storage in kilobytes |
| available_readable | string | Available storage in human-readable units |
| total | int|float | Total storage in kilobytes |
| total_readable | string | Total storage in human-readable units |
| used | int|float | Used storage in kilobytes |
| used_readable | string | Used storage in human-readable units |
| ratelimited | bool | Whether or not the wiki has been ratelimited on file uploads |
| ratelimit_percent | int | Percent of file upload ratelimit quota that has been used |
| unlimited_quota | bool | Whether or not this wiki has unlimited disk quota |
Required inputs: none
Optional inputs: none
Permanent cachability inputs: n/a
Required auth level(s):
Changes wiki state. Updates 'filetime', 'file data'
| Required inputs | ||
| Name | Type | Description |
| data | string | POSTed data for upload |
| Anti-XSS inputs -- required unless using an API key [?] | ||
| Name | Type | Description |
| ws | string | Wiki session cookie value i.e. get_cookie("ws") |
| Optional inputs | ||
| Name | Type | Description |
| filename | string | target filename if different from posted file metainformation |
| folder | string | Name of folder to upload files to |
| verbose | bool | Returns additional metadata about the file uploads |
| Required outputs | ||
| Name | Type | Description |
| success | int[0,1] | Success flag |
Permanent cachability inputs: n/a
Required auth level(s): page read write edit mod admin
Changes wiki state. Updates 'filetime', 'file data'
| Required inputs | ||
| Name | Type | Description |
| from | string | Name of file to rename |
| to | string | New name of file |
| Anti-XSS inputs -- required unless using an API key [?] | ||
| Name | Type | Description |
| ws | string | Wiki session cookie value i.e. get_cookie("ws") |
| Required outputs | ||
| Name | Type | Description |
| success | bool | Whether the operation completed successfully |
Optional inputs: none
Permanent cachability inputs: n/a
Required auth level(s): page read write edit mod admin
Changes wiki state. Updates 'filetime', 'file data'
Example invocations:
https://{wiki}.pbwiki.com/api_v2/op/RevertFile/_type/jsontext/write_key/OBVIOUS-FAKE-KEY/file/SOMEVALUE/revision/SOMEVALUE
https://{wiki}.pbwiki.com/api_v2/?op=RevertFile&_type=jsontext&write_key=OBVIOUS-FAKE-KEY&file=SOMEVALUE&revision=SOMEVALUE
Your wiki's API documentation includes examples for curl and wget as well as runnable examples in PHP.
| Required inputs | ||
| Name | Type | Description |
| file | string | File name |
| revision | epoch seconds | Revision to revert to |
| Anti-XSS inputs -- required unless using an API key [?] | ||
| Name | Type | Description |
| ws | string | Wiki session cookie value i.e. get_cookie("ws") |
| Permanent cachability inputs [?] | ||
| Name | Type | Description |
| filetime | epoch seconds | Last time any file was uploaded/delted/renamed |
| Required outputs | ||
| Name | Type | Description |
| success | bool | Whether the operation completed successfully |
Optional inputs: none
Required auth level(s): write edit mod admin
Changes wiki state. Updates 'foldertime', 'folder data'
Example invocations:
https://{wiki}.pbwiki.com/api_v2/op/CreateFolder/_type/jsontext/mod_key/OBVIOUS-FAKE-KEY/folder/Some+Folder
https://{wiki}.pbwiki.com/api_v2/?op=CreateFolder&_type=jsontext&mod_key=OBVIOUS-FAKE-KEY&folder=Some+Folder
Your wiki's API documentation includes examples for curl and wget as well as runnable examples in PHP.
| Required inputs | ||
| Name | Type | Description |
| folder | string | Folder name [folder created if folder does not exist] |
| Anti-XSS inputs -- required unless using an API key [?] | ||
| Name | Type | Description |
| ws | string | Wiki session cookie value i.e. get_cookie("ws") |
| Required outputs | ||
| Name | Type | Description |
| success | bool | Whether the operation completed successfully |
Optional inputs: none
Permanent cachability inputs: n/a
Required auth level(s): mod admin
Changes wiki state. Updates 'foldertime', 'folder data'
Example invocations:
https://{wiki}.pbwiki.com/api_v2/op/DeleteFolder/_type/jsontext/mod_key/OBVIOUS-FAKE-KEY/folder/Some+Folder
https://{wiki}.pbwiki.com/api_v2/?op=DeleteFolder&_type=jsontext&mod_key=OBVIOUS-FAKE-KEY&folder=Some+Folder
Your wiki's API documentation includes examples for curl and wget as well as runnable examples in PHP.
| Required inputs | ||
| Name | Type | Description |
| folder | string | Folder name [folder must exist] |
| Anti-XSS inputs -- required unless using an API key [?] | ||
| Name | Type | Description |
| ws | string | Wiki session cookie value i.e. get_cookie("ws") |
| Optional inputs | ||
| Name | Type | Description |
| recurse | bool | Recurse. Default is false. |
| Required outputs | ||
| Name | Type | Description |
| success | bool | Whether the operation completed successfully |
Permanent cachability inputs: n/a
| Notes |
| If recurse is true, any pages in folder are deleted. If recurse is false, any pages are moved out of the folder first and are not deleted. |
Required auth level(s): mod admin
Does not change wiki state
Example invocations:
http://{wiki}.pbwiki.com/api_v2/op/GetFileFolder/_type/jsontext/read_key/OBVIOUS-FAKE-KEY/file/SOMEVALUE
http://{wiki}.pbwiki.com/api_v2/?op=GetFileFolder&_type=jsontext&read_key=OBVIOUS-FAKE-KEY&file=SOMEVALUE
Your wiki's API documentation includes examples for curl and wget as well as runnable examples in PHP.
| Required inputs | ||
| Name | Type | Description |
| file | string | File name |
| Permanent cachability inputs [?] | ||
| Name | Type | Description |
| foldertime | epoch seconds | Last time any folder was added/deleted or a page was moved into or out of a folder |
| Required outputs | ||
| Name | Type | Description |
| folder | string|false | Folder which contains page or false |
| file | string | File requested (echo of file input) |
Optional inputs: none
Required auth level(s): page read write edit mod admin
Does not change wiki state
Example invocations:
http://{wiki}.pbwiki.com/api_v2/op/GetFolderObjects/_type/jsontext/read_key/OBVIOUS-FAKE-KEY/folder/Some+Folder
http://{wiki}.pbwiki.com/api_v2/?op=GetFolderObjects&_type=jsontext&read_key=OBVIOUS-FAKE-KEY&folder=Some+Folder
Your wiki's API documentation includes examples for curl and wget as well as runnable examples in PHP.
| Required inputs | ||
| Name | Type | Description |
| folder | string | Name of folder to get objects for |
| Permanent cachability inputs [?] | ||
| Name | Type | Description |
| foldertime | epoch seconds | Last time any folder was added/deleted or a page was moved into or out of a folder |
| Required outputs | ||
| Name | Type | Description |
| objects | array | Pages and files in the folder |
Optional inputs: none
Required auth level(s): page read write edit mod admin
Does not change wiki state
Example invocations:
http://{wiki}.pbwiki.com/api_v2/op/GetFolders/_type/jsontext/admin_key/OBVIOUS-FAKE-KEY
http://{wiki}.pbwiki.com/api_v2/?op=GetFolders&_type=jsontext&admin_key=OBVIOUS-FAKE-KEY
Your wiki's API documentation includes examples for curl and wget as well as runnable examples in PHP.
| Optional inputs | ||
| Name | Type | Description |
| after | string | Specifies which record you last saw in a previous call in descending order, used for paging. If the sortby parameter is used, this will specify a value for that field. If not, this will specify a value for the name field. |
| before | string | Specifies which record you last saw in a previous call in ascending order, used for paging. If the sortby parameter is used, this will specify a value for that field. If not, this will specify a value for the name field. |
| count | int | Maximum number of records to return |
| offset | int | Number of records to skip |
| reverse | bool | Whether to reverse the order of the sorting |
| sortby | string | Which field to sort records by |
| verbose | bool | Whether to include metadata about each folder or only return an array of folder names. Default is false. |
| Permanent cachability inputs [?] | ||
| Name | Type | Description |
| foldertime | epoch seconds | Last time any folder was added/deleted or a page was moved into or out of a folder |
| Required outputs | ||
| Name | Type | Description |
| folders | array | Names of folders in the wiki |
| unfiled_count | int | Number of objects not in any folder |
Required inputs: none
Required auth level(s):
Does not change wiki state
Example invocations:
http://{wiki}.pbwiki.com/api_v2/op/GetPageFolder/page/FrontPage/_type/jsontext/read_key/OBVIOUS-FAKE-KEY
http://{wiki}.pbwiki.com/api_v2/?op=GetPageFolder&page=FrontPage&_type=jsontext&read_key=OBVIOUS-FAKE-KEY
Your wiki's API documentation includes examples for curl and wget as well as runnable examples in PHP.
| Required inputs | ||
| Name | Type | Description |
| page | string | Page name |
| Permanent cachability inputs [?] | ||
| Name | Type | Description |
| foldertime | epoch seconds | Last time any folder was added/deleted or a page was moved into or out of a folder |
| Required outputs | ||
| Name | Type | Description |
| folder | string|false | Folder which contains page or false |
| page | string | Page requested (echo of page input) |
Optional inputs: none
Required auth level(s): page read write edit mod admin
Changes wiki state. Updates 'foldertime', 'folder data'
Example invocations:
https://{wiki}.pbwiki.com/api_v2/op/RenameFolder/_type/jsontext/read_key/OBVIOUS-FAKE-KEY/folder/Some+Folder/to/Some+Value
https://{wiki}.pbwiki.com/api_v2/?op=RenameFolder&_type=jsontext&read_key=OBVIOUS-FAKE-KEY&folder=Some+Folder&to=Some+Value
Your wiki's API documentation includes examples for curl and wget as well as runnable examples in PHP.
| Required inputs | ||
| Name | Type | Description |
| folder | string | Folder name [folder must exist] |
| to | string | Destination folder name [to must not exist] |
| Anti-XSS inputs -- required unless using an API key [?] | ||
| Name | Type | Description |
| ws | string | Wiki session cookie value i.e. get_cookie("ws") |
| Required outputs | ||
| Name | Type | Description |
| success | bool | Whether the operation completed successfully |
Optional inputs: none
Permanent cachability inputs: n/a
Required auth level(s): page read write edit mod admin
Changes wiki state. Updates 'foldertime', 'folder data'
Example invocations:
https://{wiki}.pbwiki.com/api_v2/op/SetFileFolder/_type/jsontext/admin_key/OBVIOUS-FAKE-KEY/file/SOMEVALUE
https://{wiki}.pbwiki.com/api_v2/?op=SetFileFolder&_type=jsontext&admin_key=OBVIOUS-FAKE-KEY&file=SOMEVALUE
Your wiki's API documentation includes examples for curl and wget as well as runnable examples in PHP.
| Required inputs | ||
| Name | Type | Description |
| file | string | File name [ must exist] |
| Anti-XSS inputs -- required unless using an API key [?] | ||
| Name | Type | Description |
| ws | string | Wiki session cookie value i.e. get_cookie("ws") |
| Optional inputs | ||
| Name | Type | Description |
| folder | string | Folder name [folder created if folder does not exist] |
| remove | bool | Whether to remove from the folder it is in. If given, the folder parameter is ignored. |
| Required outputs | ||
| Name | Type | Description |
| success | bool | Whether the operation completed successfully |
Permanent cachability inputs: n/a
Required auth level(s):
Changes wiki state. Updates 'foldertime', 'folder data'
Example invocations:
https://{wiki}.pbwiki.com/api_v2/op/SetPageFolder/page/FrontPage/_type/jsontext/admin_key/OBVIOUS-FAKE-KEY
https://{wiki}.pbwiki.com/api_v2/?op=SetPageFolder&page=FrontPage&_type=jsontext&admin_key=OBVIOUS-FAKE-KEY
Your wiki's API documentation includes examples for curl and wget as well as runnable examples in PHP.
| Required inputs | ||
| Name | Type | Description |
| page | string | Page name [ must exist] |
| Anti-XSS inputs -- required unless using an API key [?] | ||
| Name | Type | Description |
| ws | string | Wiki session cookie value i.e. get_cookie("ws") |
| Optional inputs | ||
| Name | Type | Description |
| folder | string | Folder name [folder created if folder does not exist] |
| remove | bool | Whether to remove from the folder it is in. If given, the folder parameter is ignored. |
| Required outputs | ||
| Name | Type | Description |
| success | bool | Whether the operation completed successfully |
Permanent cachability inputs: n/a
Required auth level(s):
Does not change wiki state
Example invocations:
http://{wiki}.pbwiki.com/api_v2/op/GetFileListAsHtml/_type/jsontext/read_key/OBVIOUS-FAKE-KEY
http://{wiki}.pbwiki.com/api_v2/?op=GetFileListAsHtml&_type=jsontext&read_key=OBVIOUS-FAKE-KEY
Your wiki's API documentation includes examples for curl and wget as well as runnable examples in PHP.
| Optional inputs | ||
| Name | Type | Description |
| external | ||