Ramses Server API

The Ramses server provides a standard http(s) REST API. If you’re developping your own client (or contributing to Ramses Client), you can easily exchange data with the server using this reference.

Queries must be a POST request; the body can be either JSON or URL encoded, the Content-Type being respectively application/json or application/x-www-form-urlencoded. However, some queries (explained in this document) are not supported in the URL encoded form, so it is better to always use JSON if possible.


In URL encoded queries, all special characters should be percent-encoded (e.g. by replacing / with %2F).

Only one attribute must be set directly in the URL (like a GET request), the name of the query itself.

For now, the server only supports the UTF-8 charset, so it is not mandatory to add the charset in the Content-Type, and any value other than utf-8 will be ignored. This may change in future versions.

Here is a minimal example of a query using URL encoding:

URL: http://your.server/ramses/?createStep

POST /ramses HTTP/1.1
Host: your.server
Content-Type: application/x-www-form-urlencoded
User-Agent: Ramses v0.1.1-Alpha
Cookie: PHPSESSID=u3jb5ep3bvbrm29kutpue7t4ds
Content-Length: 153


And this is the same query using JSON encoding:

URL: http://your.server/ramses/?createStep

POST /ramses HTTP/1.1
Host: your.server
Content-Type: application/json
User-Agent: Ramses v0.1.1-Alpha
Cookie: PHPSESSID=u3jb5ep3bvbrm29kutpue7t4ds
Content-Length: 181


The parameters to use in the body are described in the next sections of this reference. The Cookie is set by the server on the first connection, the User-Agent is set by the client.

The server replies with a JSON object in the body.


For almost all queries (i.e. all but ping and login) you’ll need to be logged in. Initiating a connection to the server usually follows these steps:

  1. ping to check if the server is available, check its version and get a token.
  2. login to authenticate yourself.
  3. init to get the main data (user list, project list…).

It’s a good habit to ping the server regularly and check it’s still available, and to improve security: for each ping request, the session token changes, and you’ll have to update it for following requests.

For the examples in this documentation, we assume the ramses server is available at http://your.server/ramses/.


For the sake of readability, the JSON replies are pretty formatted with indentation and new lines in this documentation, but the server actually uses one-line replies.

Server Replies

The JSON objects sent by the server all have the same content:



remove queries do not actually delete data from the database, but set a removed attribute to true, to prevent any data loss.
For now, the only way to permanently delete data is to edit the database by yourself (using SQL queries or MySQL workbench or phpmyadmin, etc.)

There is no query yet to restore data which has been removed, but using the create queries with the same uuid as the removed item will restore it.