API

Arguments and Responses

There are two ways to pass arguments to an endpoint:

1. URL Encoding (Key-Value Pairs) – Used in GET requests.

2. JSON Encoding (Request Body) – Used in POST requests.

The method depends on the endpoint, but generally:

• GET requests → Use URL encoding.

• POST requests → Use JSON encoding.

You can find the full endpoint specifications at the bottom of this page.

params = {'path': path}import requests

# URL encoding for a GET request
params = {"key1": "value1", "key2": "value2"}
response = requests.get("https://api.example.com/endpoint", params=params)

# JSON encoding for a POST request
data = {"key1": "value1", "key2": "value2"}
response = requests.post("https://api.example.com/endpoint", json=data)

This ensures proper data formatting based on the request type.

Handling API Responses

All API requests return JSON data in the following structure:

{
    "request_time": time,  
    "message": data  
}

The request_time field indicates how long the server took to process the request, while the message field contains the actual response data.

Extracting Data in Python

Using the requests library:

import requests

response = requests.get(f'{API_URL}/version', headers=auth_header)
version = response.json()['message']
print(version)  # Example output: 3.3.0

Using the Marple SDK:

from marple import Marple

m = Marple(ACCESS_TOKEN)
response = m.get('/version')
print(response.json()['message'])  # Example output: 3.3.0

Always access the message key to extract the relevant data from the response.

Access Token

Authentication is done by passing an access token in the Authorization header in Bearer token format:

Authorization: Bearer <access-token>

Generate and manage your Marple API tokens in the Marple settings tab: Settings > Api Tokens.

Create a new token with the desired expiry date and user role (editor/admin).

Tokens are only ever shown once, so keep them secure after generation.

These requests may be done in any language, but the easiest way to use the Marple API is through our Python SDK.

Administrator Privileges

Some endpoints require administrator privileges. Those will only be accessible by tokens with Admin role. Admin tokens can only be created by administrators of the workspace.

Changing the role of a user can be done in the 'Team' tab of the workspace settings (see Team and accounts).