Cartum API Documentation

API Gateway

The API gateway is accessible at http(s)://<DOMAIN>/api/

Authentication

To use the API, you need a login and password, which can be created in the site's admin panel under the Settings - Users tab.

Protocol

The API operates over HTTP/HTTPs. Functions are passed through the URL as http://<DOMAIN>/api/<FUNCTION>/.

If the site uses HTTPS, the API must be accessed via HTTPS as well.

Request Methods

Type	Details	Example
JSON POST (Recommended)	The Content-type: application/json field must be passed in the request header for correct data processing on the server. Parameters should be passed in the body of the request in JSON format	`{"param_1":"1","param_2":"4"}`
Standard POST (Deprecated)	It is transmitted as standard according to HTTP 1.1 specifications (in the request body). The Content-type: multipart/form-data or Content-type: application/x-www-form-urlencoded header must be passed.	param_1=2&param_2=4

All field names and values should be encoded in UTF-8. Responses are also returned in UTF-8 encoding.

Important Notes

When using UTF-8 encoding in requests, data should be transmitted without the BOM line.
Responses are similarly returned without BOM.
It's strongly recommended to use JSON POST requests with Content-type:application/json header.

Starting from version 3.8.0, if you send content via JSON POST method in encoding other than UTF-8, it is necessary to specify it explicitly in the header (for example: "Content-type: application/json; charset=windows-1251").

If you need to receive a response from the server in an encoding other than UTF-8, you should also specify the Accept-Charset header with the required encoding (see https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.2).

Response Format

Responses are always in JSON format and include the following fields:

Field Meaning Description

status

Indicates the status of the request

Possible values:

"OK" (success),
"UNAUTHORIZED" (authorization required or token not provided),
"AUTHORIZATION_ERROR" (authorization error),
"EXCEPTION" (server error),
"ERROR" (general error, with details in response.message),
"EMPTY" (no results),
"UNDEFINED_FUNCTION" (nonexistent function called),
"HTTP_ERROR" (HTTP error, with response.code and response.message explaining the error).

response Contains the server's response, dependent on the status and function called.

JSON POST request example

POST https://foo.bar/api/func/action
Content-Type: application/json

{"param_1": "value_1", "param_2": "value_2"}

Server response example

Пример ответа

{
	"status": "OK",
	"response": {"foo": "bar"}
}

Logs

Logs of requests and server responses are available at http://<DOMAIN>/api/logs/. To access logs, authenticate in the admin panel at http://<DOMAIN>/edit/login.php using the API login and password.

Функции: