API Guide

Using the Marple API

1 Arguments and Responses

There are two ways of passing arguments to an endpoint: either encoded as key-value pairs in the URL or encoded as JSON in the body of the request. This depends on the endpoint, in general GET requests will use URL encoding, while POST requests will use JSON encoding. The full specification of all endpoints can be found at the bottom of the page. Here is an example of both methods in Python:

params = {'path': path}
r = requests.get(f'{API_URL}/sources/lookup', headers=auth_header, params=params)

body = {'path': '/', 'new_folder_name': 'new_folder'}
r = requests.post(f'{API_URL}/library/folder/add', headers=auth_header, json=body)

Requests will always return data as JSON with the following structure:

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

It will contain both the time the server has taken to process the request and the actual output. Decode and access the message key to extract the result:

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

Or using the Marple SDK:

from marple import Marple
m = Marple(ACCESS_TOKEN)
response = m.get('/version')
print(response.json()['message']) # 3.3.0

2 Uploading and Importing Files

In Marple files are uploaded onto a file server and then parsed into our database which we call 'importing'. Once a file has been imported into the database it is referred to as a 'source'

1. POST /library/file/upload

Upload a file onto the file server. URL query parameters:

  • path: the path to the directory on the file server where the file should be uploaded

File body parameters:

  • file: the file contents

=> Returns "OK", and confirms the path where the file is uploaded

API_URL = 'https://app.marpledata.com/api/v1'
endpoint = '/library/file/upload'
token = '...'
auth_header = {'Authorization': f'Bearer {token}'}

files = {'file': open('myfile.csv', 'rb')}
target_dir = '/'  # file server root dir
target_dir = '/sub_dir' # or a subdirectory

r = requests.post(
  params={'path': target_dir}, 

r.json()['message'] == {'status': 'OK', 'path': 'sub_dir'}

2. POST /library/file/import

Start importing a file into the database JSON body parameters:

  • path: the path to where the file is located on the server

  • plugin: the plugin to be used for importing the file

  • config: (optional) the configuration for the plugin

=> Returns the source_id of the file in the database, and the metadata associated with the file

endpoint = '/library/file/import'
path = '/sub_dir/myfile.csv'
plugin = 'csv_plugin'

r = requests.post(
  json={'path': path, 'plugin': plugin}

r.json()['message'] == {
  'source_id': 1,
  'metadata': { # most plugins don't support automatic metadata extraction
    'test_reference': 14,

3. GET /sources/status

Monitor the progression of the file import process URL query parameters:

  • id: source id or array of source ids for which to request the status.

To pass an array as a query parameter use the following syntax: api_url/sources/status?id=1,2,3,...

=> Returns an array of status codes

endpoint = '/sources/status'
source_id = 1

r = requests.post(
  params={'id': source_id}

r.json()['message'] == {[{
  'source_id': 1,
  'status': 100

3 Adding Metadata

Metadata can be manipulated using the /library/metadata endpoints. Metadata is always coupled to files using the source_id and not the file name. The source id associated with a file can be found using the /sources/lookup endpoint.

1. GET /sources/lookup

Get source id associated with file. URL query parameters:

  • path: full file path of file to lookup

=> Returns the source_id of the file

endpoint = '/sources/lookup'
path = '/sub_dir/myfile.csv'

r = requests.post(f'{base_url}{endpoint}', headers=auth_header,
                  params={'path': path})

2. POST /library/metadata

Add metadata to a source JSON body parameters:

  • source_id: the source to add the metadata to

  • path: (optional) If the file does not yet have a source_id it can be referenced by its path. This function will return the source id assigned to the file in this case

  • metadata: Key-value pairs to add to metadata.

=> Returns source_id and "OK" message

source_id = 1
metadata = {'test_operator': 'Arthur', 'test_reference': 'BX-14'}

endpoint = '/library/metadata'
r = requests.post(
    'source_id': source_id,
    'metadata': metadata

4 Sharing Projects and Sources

A project can be shared using the /library/share endpoints. Make sure that the target project exists in the app before using these endpoints.

1 POST /library/share/new

Generate a new share link id JSON body parameters

  • workbook_name: name of the project you wish to share

  • source_ids: sources to include in the share

=> Returns new share id

endpoint = '/library/share/new'
name = 'example'
source_ids = [1,2,3]

r = requests.post(
    'workbook_name': name,
    'source_ids': source_ids

2 POST /library/share/<share_id>/add

Add data to share id JSON body parameters:

  • workbook_name: change project for this share

  • source_ids: Source ids to add to share

=> Returns new share id with updated content

share_id = '1234567890abcdef'
endpoint = f'/library/share/{share_id}/add'
source_ids = [4,5,6]

r = requests.post(
    'workbook_name': name,
    'source_ids': source_ids

3. POST /library/share/<share_id>/link

Genrate a sharable link which opens the project with its source ids JSON body parameters:

  • url: (optional) set base URL for the share link

=> Returns clickable link

share_id = '1234567890abcdef'
url = 'https://yourcompany.marpledata.com'
endpoint = f'/library/share/{share_id}/link'

  base_url + endpoint,
  args={'url': url}
) # Returns https://yourcompany.marpledata.com/?share=1234567890abcdef

5 API Example Repository

Marple maintains a public repository with an example API usecase: 🔗 https://gitlab.com/marple-public/marple-api-exampleThis script runs a simulated experiment, logs the data, uploads and imports it into marple and then generates a share link ready for visualisation.In the public repository there are example scripts for both Python and MATLAB.

6 API Reference

Marple Swagger API Reference

Last updated