The HTTP API uses specific http URLs, http request codes and http response codes for each function. It is the API used by the webGUI.

General Concept

The HTTP API's prefix is /http.

Model names and field id's use snake case in singular. URL's always use the model name in singular. If the return is an array of multiple objects or object id's then the field name is in plural.

The model content has the following JSON structure:

  • id contains the model ID as a string: "id": "ID_STRING"
  • one to one relationships should reference the model name in singular with the referenced ID string: "model_name": "ID_STRING"
  • one to many relationships should be built using the model name in plural followed by an array of the referenced ID's: "model_names": [ ARRAY_OF_ID_STINGS ]


URL Concept

The general URL concept looks like this: /http/model_name/ID?QUERY_STRING

To list all entries: GET /http/model_name

To query the entries: GET /http/model_name?QUERY_STRING

To create a new entry: POST /http/model_name

To get a single entry: GET /http/model_name/ID

To modify an entry: PATCH /http/model_name/ID

To delete an entry: DELETE /http/model_name/ID


The Authentication Token is sent in the Authorization field of the http request header.



In order to create or modify an entry we send a JSON payload with the request.

To create an entry we send POST a request with the content of some of the fields. Please be aware, that some fields are mandatory and that not all the fields can be set during the creation of an entry. To find out about the specific use please check the documentation of the model.

Create entry payload example:

    "field_name": "FIELD_VALUE"

To modify and entry we send a PATCH request with only the modified fields in a specific structure. A set structure to set or modify a field, and an unset structure to delete the content of a field.

Modify entry payload example:

    "field_name": { "set": "FIELD_VALUE" },
    "field_name": "unset"


HTTP Response Codes

HTTP response codes on success:

  • 200 (OK): default response code, when everything went well and you're receiving a payload.
  • 204 (No Content): response when there is no payload, which you get on delete and sometimes on modify too.

HTTP response codes on error:

  • 400 (Bad Request): wrong user input (and any other unhandled error)
  • 401 (Unauthorized): if the user is not authorized to perform this task. This either means that you're authorization token is invalid or that you're trying to access some other users data.
  • 500 (Internal Server Error): The server was not able to parse the request payload.

Response Payload per Action

The response payloads are model specific and should be checked in the model documentations. however there are some general rules how a payload looks.

When you're receiving a list of entries, you're receiving the following structure:

    "model_names": [
            "id": "ITEM_ID",
            "field_name": "FIELD_CONTENT"
            "id": "ITEM_ID",
            "field_name": "FIELD_CONTENT"

When you get one specific entry by it's ID, or when you create a new entry you're receiving the following structure:

    "model_name": {
        "id": "ITEM_ID",
        "field_name": "FIELD_CONTENT"

Error Response Payload

On error you're receiving an error message as payload.

    "error": "ERROR_MESSAGE"