API

Getting an API key

Authentication is done by passing an access token in the Authorization header of your HTTP request:

Authorization: Bearer <access-token>

Generate and manage your Marple API tokens in the settings tab. Click "Add token" to generate a new token with the desired expiry date and user role (editor/admin). Tokens are only shown once, so keep them securely stored after generation.

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

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.

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.

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).