====== JSON-RPC API ======

This API provides access to all [[Remote API]] functionality using a JSON based API.


===== Accessing The JSON-RPC Interface =====

You can access the JSON-RPC interface via the following URL:

  http(s)://<your wiki/domain/ip>/lib/exe/jsonrpc.php


The API allows access via two different protocols:

  - A simplified RPC protocol, where the method to call is passed as a path segment and the body contains the array of parameters to pass
  - Standard conform [[https://www.jsonrpc.org/|JSON-RPC calls]] either using version 1.0, 1.1 or 2.0.

Please note: this is not a REST API. All calls have to made as ''POST'' requests. Your requests need to contain a ''Content-Type: application/json'' header.

Refer to [[authentication]] on how to authenticate API requests.

==== Simplified Access ====

This is the easiest way to interact with the API when you're implementing it yourself. It is also the format documented in the [[https://www.dokuwiki.org/lib/exe/openapi.php|API Explorer]].

The function you want to call has to be given as a path segment:

  http(s)://<your wiki/domain/ip>/lib/exe/jsonrpc.php/<function>

All parameters are either as passed **by order** in a JSON Array or **by name** in a JSON Object in the body of the request. The latter is preferred. Here's an example using curl:

  curl http://localhost/dokuwiki/lib/exe/jsonrpc.php/core.getPageInfo \
     -H 'Content-Type: application/json' \
     -H "Authorization: Bearer $token" \
     -d '{"page": "wiki:syntax"}'

==== JSON-RPC Standard ====

The main difference to the simplified form is that all info, including the method to call is passed as body:

  curl http://localhost/dokuwiki/lib/exe/jsonrpc.php \
     -H 'Content-Type: application/json' \
     -H "Authorization: Bearer $token" \
     -d '{"jsonrpc": "2.0", "id": "something", "method": "core.getPageInfo", "params": {"page": "wiki:syntax"}}'

Please note, when using version 2.0, batching multiple calls is not supported. Refer to the [[https://www.jsonrpc.org/specification|Specification on how to use this format]].


==== Results ====

Results are always returned as a JSON object.

Here's an example response for a ''core.getPageInfo'' call:

<code>
{
          "result": {
                  "id": "wiki:syntax",
                  "revision": 1698917236,
                  "size": 21393,
                  "title": "wiki:syntax",
                  "permission": 255,
                  "hash": "",
                  "author": ""
          },
          "error": {
                  "code": 0,
                  "message": "success"
          }
}
</code>

The result object is the result of your call, the error object will have a non-zero code if something goes wrong.

===== Available Functions =====

Please refer to the [[https://www.dokuwiki.org/lib/exe/openapi.php|API Explorer]] to learn which calls are available and what responses to expect. You can also call the explorer on your own wiki instance at ''%%http(s)://yourwiki/dokuwiki/lib/exe/openapi.php%%''.

===== Open API Specification =====

An [[https://www.openapis.org/|OpenAPI]] Specification (using Version 3.1) is available from the API Explorer. It can be used with any OpenAPI compatible tool to visualize the API, validate requests or even generate appropriate API client code.