On this page

Signal Upload (Binary)

POST /api/signals/upload

Uploads a signal as multipart/form-data. Unlike POST /api/signals/send (inline JSON), the file contents are transferred directly – the server needs no host file path and therefore no host filesystem access. This is the recommended way for large signals and works inside the Flatpak sandbox too.

Tip

Step-by-step guide: Import data from Python & MATLAB

Request

POST /api/signals/upload HTTP/1.1
Host: localhost:5678
Content-Type: multipart/form-data; boundary=...

Form Fields

Field	Type	Required	Description
`file`	file	Yes	`.npz` or `.mat` with arrays `y` (required), `x`, `z` (optional)
`meta`	JSON string	No	`{name, y_unit, x_unit, z_unit, target_source_id, overwrite}`

Metadata can be passed either as a meta JSON field or as individual form fields (name, y_unit, x_unit, z_unit, target_source_id). name and target_source_id are required. Set overwrite to true to replace an existing signal with the same name in the target source.

File format

NumPy (.npz): Must contain an array named y. Optional: x and z.
MATLAB (.mat): Must contain a variable named y. Optional: x and z.

Response

Status Code: 200 OK

{
  "status": "ok",
  "result": {
    "signal_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "name": "Large Signal",
    "sample_count": 1000000
  }
}

Errors

Status	Meaning
`400`	Missing `file` field or invalid metadata
`404`	`target_source_id` not found
`415`	Unsupported file type (only `.npz` / `.mat`)
`500`	Server error while storing or loading the file

POST /api/signals/upload_batch

Uploads multiple signals in a single request. This saves the HTTP round-trips of many individual uploads – ideal for pushing many (large) channels, e.g. an entire measurement, efficiently at once.

Request

POST /api/signals/upload_batch HTTP/1.1
Host: localhost:5678
Content-Type: multipart/form-data; boundary=...

Form Fields

Field	Type	Required	Description
`file`	file (repeated)	Yes	One `.npz`/`.mat` upload per signal
`meta`	JSON array or object	No	One object per file (same order), or a single object applied to all files
`target_source_id`	string	No	Default target for signals without their own `target_source_id`

Each meta object accepts the same fields as /api/signals/upload, including overwrite. Files are matched to meta entries by order.

Response

Status Code: 200 OK

{
  "status": "ok",
  "result": {
    "signals": [
      {"signal_id": "...", "name": "Channel A", "sample_count": 1000000},
      {"signal_id": "...", "name": "Channel B", "sample_count": 1000000}
    ],
    "errors": []
  }
}

A single failing signal does not abort the request. Successful imports are listed in signals, failures in errors (each with index and error).

Errors

Status	Meaning
`400`	Missing `file` field or `meta` is not a JSON array
`500`	Server error