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 |
|
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¶m_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:
|
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.
Options: