JSON API: /wiki

(⬑JSON API Index)

Jump to:

Page List

Returns a list of all pages, not including their content (which can be arbitrarily large).

Status: implemented 201109xx

Required privileges: "j" or "o"

Request: /json/wiki/list


Response payload: format depends on "verbose" option

Non-verbose mode:


In verbose mode:

"name":"Apache On Windows XP",
"size":793 /* in bytes */

The verbose-mode output is the same as the /json/wiki/get output, but without the content. The size property of each reflects the byte length of the raw (non-HTMLized) page content.

Potential TODOs:

Fetch a Page

Fetches a single wiki page, including content and significant metadata.

Status: implemented 20110922, but response format may change.

Required privileges: "j" or "o"


Response payload example:

"name": "Fossil",
"uuid": "...hex string...",
"parent": "uuid of parent (not set for first version of page)",
"user": "anonymous",
"timestamp": 1286143975,
"size": 1906, /* In bytes, not UTF8 characters!
                 Affected by format option! */
"content": "..."

FIXME: it's missing the mimetype (that support was added to fossil after this was implemented).

If given no page to load, or if asked to get a page which does not exist, an error response is generated (a usage- or resource-not-found error, respectively).

Options (via CLI/GET/POST.payload):


Create or Save Page

Status: implemented 20110922.

Required privileges: "k" (save) or "f" (create)


These work only in HTTP mode, not CLI mode. (FIXME: now that we can simulate POST from a file, these could be used in CLI mode.)

The semantic differences between save and create are:

Response payload example:

The same as for /json/wiki/get but the page content is not included in the response (only the metadata).

Request options (via GET or POST.payload object):

Wiki Diffs

Status: implemented 20120304

Required privileges: "h"


Response payload example:

  "diff":"@@ -1,4 +1,9 @@...<SNIP>..."


This command does not verify that both UUIDs actually refer to the same page name, but do verify that they refer to wiki content.

Trivia: passing the same UUIDs to the /json/diff command will produce very different results - that one diffs the manifests of the commits.



Status: implemented 20120310

Required privileges: "k" (to limit its use to only those who can edit wiki pages). This limitation is up for debate/reconsideration.


This command wiki-processes arbitrary text sent from the client. To help curb potential abuse, its use is restricted to those with "k" access rights.

The POST.payload property must be either:

  1. A string containing Fossil wiki markup.

  2. An Object with a body property holding the text to render and a mimetype property describing the wiki format: text/x-fossil-wiki (the default), text/x-markdown, or text/plain. Any unknown type is treated as text/x-fossil-wiki.

The response payload is a string containing the rendered page. Whether or not "all HTML" is allowed depends on site-level configuration options, and that changes how the input is processed.

Note that the links in the generated page are for the HTML interface, and will not work as-is for arbitrary JSON clients. In order to integrate the parsed content with JSON-based clients the HTML will probably need to be post-processed, e.g. using jQuery to fish out the links and re-map wiki page links to a JSON-capable page handler.

Notes and TODOs

Potential TODOs: