Japanese language version

Document for Mass Spectrometry Data Processing API

📋 Contents

1. Quickstart
2. API Overview
3. Setup Guide
4. API Specifications
5. Implementation examples by language
6. Troubleshooting

---

🚀 Quickstart

Basic usage flow

1. Sample creation -> POST /io_create_sample
2. Adding Spectrum -> POST /io_add_scan
3. Adding notes (optional) -> POST /io_add_annotation
4. Saving data -> POST /io_flush
5. Data Retrieval -> POST /io_get_spectrum

Minimal operation check

# 1. Sample creation
curl -X POST http://localhost:8191/io_create_sample \
-H "Content-Type: application/json" \
-d "null"# 2. Check the total spectrum number
curl -X POST http://localhost:8191/io_get_spectra_count \
-H "Content-Type: application/json" \
-d "null"

---

📖 API Overview

Basic Information

• Base URL: http://localhost:8191/
• Protocol: HTTP REST API
• Method: POST（All endpoints）
• Data Format: JSON
• Authentication: Unnecessary
• Character encoding: UTF-8

Key Features

• Mass Spectral Data Submission
• Adding Peak Annotations
• Data Persistence
• Retrieving Spectrum Data

---

Setup Guide

Server requirements

• Mass++ Server: Running on port 8191
• OS: Compatible with Windows, macOS, and Linux

Connection confirmation

# Server operation check
curl -X POST http://localhost:8191/io_get_spectra_count \
-H "Content-Type: application/json" \
-d "null"

Success response:

{"count": 0}

---

API Specifications

Common Specifications

HTTP header

POST /endpoint
Content-Type: application/json

Response Format

• Success: HTTP status 200 + JSON data
• Error: HTTP status 400-500 + error message

Error Handling

{
"error": "Error message",
"code": "ERROR_CODE"
}

---

Data Management API

1. Sample creation

POST /io_create_sampleContent-Type: application/jsonnull

Response

{
"id": "sample_12345"
}

---

2. Adding scan data

POST /io_add_scanContent-Type: application/json

Request body

{
"id": "sample_12345",
"msLevel": 1,
"precursorMz": -1.0,
"rt": 123.45,
"points": [
{"x": 100.0, "y": 1000.0},
{"x": 101.0, "y": 500.0}
],
"centroidMode": true,
"minMz": 99.5,
"maxMz": 101.5
}

Parameter details

Field	Type	Required	Description	Example
id	string	Yes	Sample ID	"sample_12345"
msLevel	integer	Yes	MS level	1, 2, 3...
precursorMz	number	Yes	precursor m/z	123.45 (-1.0 for MS1)
rt	number	Yes	Retention time (sec)	60.5
points	array	Yes	Spectrum data	[{"x": m/z, "y": intensity}]
centroidMode	boolean	Yes	Centroid mode	true/false
minMz	number	Yes	Minimum m/z for display	99.0
maxMz	number	Yes	Maximum m/z for display	200.0

Response

{
"status": "success"
}

---

3. Adding peak annotation

POST /io_add_annotationContent-Type: application/json

Request body

[
{
"name": "C6H6O+",
"mass": 94.0419,
"intensity": 1000.0,
"image": "base64_encoded_image",
"id": "sample_12345"
}
]

---

4. Saving data

POST /io_flushContent-Type: application/json

Request body

{
"id": "sample_12345",
"index": 0
}

---

📤 Data Retrieval API

5. Obtaining the total number of spectra

POST /io_get_spectra_countContent-Type: application/jsonnull

Response

{
"count": 150
}

---

6. Obtaining the current index

POST /io_get_current_indexContent-Type: application/jsonnull

Response

{
"index": 5
}

---

7. Obtaining spectrum data

POST /io_get_spectrumContent-Type: application/json

Request body

{
"index": "0"
}

Response

{
"id": "sample_12345",
"msLevel": 1,
"rt": 123.45,
"precursorMz": -1.0,
"minMz": 99.5,
"maxMz": 200.8,
"points": [
{"x": 100.0, "y": 1000.0},
{"x": 101.0, "y": 500.0}
]
}

---

💻 Implementation examples by language

🐍 Python

importrequestsimportjsondefcall_api(endpoint, data=None):
url=f'http://localhost:8191/{endpoint}'headers= {'Content-Type': 'application/json'}
body=json.dumps(data) ifdataelse'null'response=requests.post(url, headers=headers, data=body)
returnresponse.json()
# Sample creationsample=call_api('io_create_sample')
sample_id=sample['id']
# Adding Spectrumscan_data= {
'id': sample_id,
'msLevel': 1,
'precursorMz': -1.0,
'rt': 60.0,
'points': [{'x': 100.0, 'y': 1000.0}],
'centroidMode': True,
'minMz': 99.0,
'maxMz': 101.0
}
call_api('io_add_scan', scan_data)
call_api('io_flush', {'id': sample_id, 'index': 0})

☕ Java

importjava.net.http.HttpClient;
importjava.net.http.HttpRequest;
importjava.net.http.HttpResponse;
importjava.net.URI;
importcom.fasterxml.jackson.databind.ObjectMapper;
publicclassMassSpecAPI {
privatestaticfinalStringBASE_URL = "http://localhost:8191/";
privatefinalHttpClientclient = HttpClient.newHttpClient();
privatefinalObjectMappermapper = newObjectMapper();
publicStringcreateSample() throwsException {
HttpRequestrequest = HttpRequest.newBuilder()
.uri(URI.create(BASE_URL + "io_create_sample"))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString("null"))
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
// Extracting IDs from JSON responsesreturnmapper.readTree(response.body()).get("id").asText();
}
publicvoidaddScan(StringsampleId, double[] mzValues, double[] intensities) throwsException {
StringBuilderpointsJson = newStringBuilder("[");
for (inti = 0; i < mzValues.length; i++) {
if (i > 0) pointsJson.append(",");
pointsJson.append(String.format("{\"x\":%.3f,\"y\":%.1f}", mzValues[i], intensities[i]));
}
pointsJson.append("]");
Stringjson = String.format(
"{\"id\":\"%s\",\"msLevel\":1,\"precursorMz\":-1.0," +
"\"rt\":60.0,\"points\":%s,\"centroidMode\":true," +
"\"minMz\":%.1f,\"maxMz\":%.1f}",
sampleId, pointsJson.toString(), mzValues[0] - 1, mzValues[mzValues.length - 1] + 1
);
HttpRequestrequest = HttpRequest.newBuilder()
.uri(URI.create(BASE_URL + "io_add_scan"))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(json))
.build();
client.send(request, HttpResponse.BodyHandlers.ofString());
}
}

🐘 PHP

<?phpclass MassSpecAPI {
private$baseUrl = 'http://localhost:8191/';
privatefunctioncallAPI($endpoint, $data = null) {
$url = $this->baseUrl . $endpoint;
$json = $data ? json_encode($data) : 'null';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $json);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
returnjson_decode($response, true);
}
publicfunctioncreateSample() {
$result = $this->callAPI('io_create_sample');
return$result['id'];
}
publicfunctionaddScan($sampleId, $mzValues, $intensities) {
$points = [];
for ($i = 0; $i < count($mzValues); $i++) {
$points[] = ['x' => $mzValues[$i], 'y' => $intensities[$i]];
}
$scanData = [
'id' => $sampleId,
'msLevel' => 1,
'precursorMz' => -1.0,
'rt' => 60.0,
'points' => $points,
'centroidMode' => true,
'minMz' => min($mzValues) - 1,
'maxMz' => max($mzValues) + 1
];
return$this->callAPI('io_add_scan', $scanData);
}
publicfunctionflushData($sampleId) {
return$this->callAPI('io_flush', ['id' => $sampleId, 'index' => 0]);
}
}
// Usage example$api = newMassSpecAPI();
$sampleId = $api->createSample();
$api->addScan($sampleId, [100.0, 101.0, 102.0], [1000, 500, 750]);
$api->flushData($sampleId);
?>

JavaScript (Node.js)

constaxios=require('axios');classMassSpecAPI{constructor(baseUrl='http://localhost:8191/'){this.baseUrl=baseUrl;this.headers={'Content-Type': 'application/json'};}asynccallAPI(endpoint,data=null){consturl=`${this.baseUrl}${endpoint}`;constbody=data ? JSON.stringify(data) : 'null';constresponse=awaitaxios.post(url,body,{headers: this.headers});returnresponse.data;}asynccreateSample(){constresult=awaitthis.callAPI('io_create_sample');returnresult.id;}asyncaddScan(sampleId,mzValues,intensities){constpoints=mzValues.map((mz,i)=>({x: mz,y: intensities[i]}));constscanData={id: sampleId,msLevel: 1,precursorMz: -1.0,rt: 60.0,points: points,centroidMode: true,minMz: Math.min(...mzValues)-1,maxMz: Math.max(...mzValues)+1};returnawaitthis.callAPI('io_add_scan',scanData);}}// Usage example(async()=>{constapi=newMassSpecAPI();constsampleId=awaitapi.createSample();awaitapi.addScan(sampleId,[100.0,101.0,102.0],[1000,500,750]);awaitapi.callAPI('io_flush',{id: sampleId,index: 0});})();

---

Typical workflow

Data registration flow

1. Sample creation (/io_create_sample)
->
2. Adding Spectrum (/io_add_scan) * N times
->
3. Adding annotation (/io_add_annotation) # Optional
->
4. Saving data (/io_flush)

Data Extraction Flow

1. Check the total number (/io_get_spectra_count)
->
2. Obtaining spectrum (/io_get_spectrum) * N times
->
3. Data analysis and export

---

Troubleshooting

Common errors

Connection Error

Error: Connection refused

Solution: Check that the Mass++ server is running and that port 8191 is running

JSON format error

HTTP 400: Invalid JSON

Solution: Check the format of the request body and the Content-Type header

Empty response

HTTP 200: Empty response

Solution: Check API endpoints and validate request parameters

How to debug

1. Basic Connection Test

curl -v -X POST http://localhost:8191/io_get_spectra_count \
-H "Content-Type: application/json" \
-d "null"

2. Response confirmation

# Detailed HTTP response display
curl -i -X POST http://localhost:8191/io_create_sample \
-H "Content-Type: application/json" \
-d "null"

---

📞 Support

API Specifications

• Version: 1.0
• Last update: July, 2025

Notes

• All endpoints use the POST method.
• Send null even if no request body is required.
• Be careful when converting numbers to strings (such as index parameters).
• Base64 encoded image data can be large in size.

---

This API is designed for efficient processing of mass spectrometry data. Please refer to the implementation examples in each language to develop a client suitable for your environment.