The results you need.
Precisely defined.

01 / THE COMPLETE CATALOG

Surface and source, clearly separated.

These are the measurements present in the bundled engines and normative tables. “Available” means a supported output exists; undefined numerical values can still be null. Each selectable ID is independent.

Discover valid selectors

GET /v1/metrics?montage=LE
GET /v1/metrics/surface.coherence.band?montage=LE
GET /v1/metrics/source.loreta.coherence

The catalog lists id, available_values, units, columns, cell count, conditions and per-reference availability. A metric detail also returns its exact cells list. Select labels exactly as returned—including letter case and pair order. Catalog requests do not read EEG data.

02 / WHAT EACH NUMBER MEANS

Measurement definitions.

Frequency bands

Surface spectra use 2-second Hann windows with 75% overlap at 128 Hz after a 1–40 Hz prefilter. Complete windows stay inside retained signal runs. Band-power integration uses a lower-inclusive, upper-exclusive interval. Regional source outputs use their own band-pass filtering and the eight source bands below.

Surface absolute and relative power also provide columns 1 Hz through 30 Hz; each covers [k, k+1) Hz. Voxel current density instead uses 30 frequency coordinates at 1–30 Hz. The ten power ratios are listed in the power-ratio definition above.

Spatial labels

Result labels preserve the normative table’s spelling: acquisition metadata uses Fp1, but its result label uses uppercase FP1. Surface single-electrode labels include their reference, such as FP1-LE or FP1-AVE. Pair labels such as FP1-FP2 retain their documented order. The source atlas contains 2,394 voxel indices; current-density output includes MNI and Talairach coordinates.

Regional source power covers 88 cells: Brodmann areas 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 17, 18, 19, 20, 21, 22, 23, 24, 25, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46 and 47, plus amygdala and hippocampus, in each hemisphere. Labels include 7 L, Amy L and Hip R. Source coherence provides the 1,936 pairs in its catalog; this is not every possible combination of 88 regions.

03 / RECORDING INPUT

Upload the signal once.

Create immutable acquisition metadata with a unique Idempotency-Key. Use a pseudonymous participant reference. Required fields and a complete valid example:

POST /v1/recordings
Authorization: Bearer YOUR_API_KEY
Idempotency-Key: recording-001
Content-Type: application/json

{
  "channels": ["Fp1", "Fp2", "F3", "F4", "C3", "C4", "P3", "P4",
    "O1", "O2", "F7", "F8", "T3", "T4", "T5", "T6", "Cz", "Fz", "Pz", "A1", "A2"],
  "sample_rate_hz": 250,
  "units": "uV",
  "dtype": "float32-le",
  "layout": "sample-major",
  "reference": "common",
  "reference_electrode": "CPz",
  "age_years": 30,
  "condition": "EC",
  "started_at": "2026-09-22T10:00:00Z",
  "subject_ref": "participant-042",
  "device_id": "recorder-03",
  "device_model": "your-device-model",
  "acquisition_version": "1.0",
  "line_frequency_hz": 50
}

All 19 scalp electrodes are required; A1/A2 are optional depending on the analysis reference. Map T7/T8/P7/P8 to T3/T4/T5/T6 before upload. Sampling rate is an integer from 128 to 2,000 Hz. Convert ADC values to µV on the client. reference is common, linked_ears or average; a common reference requires its electrode name. Conditions are EC (eyes closed) or EO (eyes open), and the timestamp needs a timezone. Mains frequency is 50 or 60 Hz.

Send binary chunks

PUT /v1/recordings/RECORDING_ID/chunks/0
Authorization: Bearer YOUR_API_KEY
Content-Type: application/octet-stream
X-Start-Sample: 0
X-Content-SHA256: SHA256_OF_DECODED_BYTES

<sample-major little-endian float32 bytes>

Each frame contains every channel in the declared order. Sequence starts at zero. Each encoded and decoded chunk may be at most 1 MiB; optional Content-Encoding: gzip compresses transfer. A recording is limited to 4,096 chunks, 256 MiB and one hour. Out-of-order chunks are accepted; overlaps are rejected.

POST /v1/recordings/RECORDING_ID/seal
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{ "total_chunks": 1, "total_samples": 4000 }

Use your actual totals. At least ten seconds are required. Sealing verifies contiguous sample coverage and makes the recording immutable. Signal upload may stream during acquisition; final screening and analysis begin after sealing.

04 / ARTIFACT SCREENING

One screening request. A shared mask.

POST /v1/artifact-rejection
Authorization: Bearer YOUR_API_KEY
Idempotency-Key: screening-001
Content-Type: application/json

{ "recording_id": "RECORDING_ID" }

The response is HTTP 202 with a job ID and recording ID. NG, Deep, amplitude guard and run hygiene inspect the original waveform and accumulate a union of rejected intervals. File-level amplitude validity can make a recording ineligible for downstream analysis. Poll the job and download artifacts.json from its result manifest.

The result includes original sample rate and length, per-pass rejected counts and retained duration, final retained/rejected intervals, an original-to-retained index map, validity findings and analysis_eligible. No waveform is returned.

{
  "coordinate_system": "original_recording",
  "interval_convention": "[start_sample, stop_sample)",
  "rejected_intervals": [
    { "start_sample": 1000, "stop_sample": 1250,
      "start_seconds": 4.0, "stop_seconds": 5.0 }
  ]
}

This illustrative interval removes samples 1000–1249 from a 250 Hz recording. Apply the final union once to your original local data. If you display successive shortened timelines, use original_to_retained; never reuse original indices directly against an already shortened signal.

For a complete signal no larger than 1 MiB, the same endpoint also accepts a binary body with X-Recording-Metadata containing the metadata JSON and X-Content-SHA256. It stores and seals that signal automatically. Larger or interrupted uploads should use chunks.

05 / REQUEST ONLY WHAT YOU NEED

Select measurements, values and dimensions.

POST /v1/recordings/{id}/analyses reuses the stored recording and its artifact mask. You may submit before screening completes; the job waits. An ineligible or failed screening prevents analysis.

Example: Alpha absolute-power Z-scores at two electrodes

POST /v1/recordings/RECORDING_ID/analyses
Authorization: Bearer YOUR_API_KEY
Idempotency-Key: alpha-z-001
Content-Type: application/json

{
  "artifact_job_id": "ARTIFACT_JOB_ID",
  "montage": "LE",
  "outputs": [{
    "metric": "surface.absolute_power.band",
    "values": ["z"],
    "cells": ["FP1-LE", "FP2-LE"],
    "columns": ["Alpha"]
  }]
}

Example: Combine surface connectivity with source power

{
  "artifact_job_id": "ARTIFACT_JOB_ID",
  "montage": "LE",
  "outputs": [
    { "metric": "surface.coherence.band", "values": ["raw", "z"],
      "cells": ["FP1-FP2"], "columns": ["Theta", "Alpha"] },
    { "metric": "surface.amplitude_asymmetry.band", "values": ["raw", "z"] },
    { "metric": "source.loreta.power", "values": ["raw", "z"],
      "cells": ["7 L", "7 R"], "columns": ["alpha_1", "alpha_2"] },
    { "metric": "source.eloreta.coherence", "values": ["raw"] }
  ]
}

Example: All supported measurements in one bundle

{
  "artifact_job_id": "ARTIFACT_JOB_ID",
  "montage": "LE",
  "outputs": "all",
  "delivery": "bundle"
}

all includes every available variant for the chosen montage. With AVE, it excludes surface coherence and phase lag. It includes only raw eLORETA coherence. Explicitly asking for an unsupported combination returns 422 instead of silently omitting it.

Example: Only selected voxel Z-scores

{
  "artifact_job_id": "ARTIFACT_JOB_ID",
  "montage": "AVE",
  "outputs": [{
    "metric": "source.current_density",
    "values": ["z"],
    "cells": ["0", "1", "2"],
    "columns": ["8 Hz", "9 Hz", "10 Hz"]
  }]
}

The NPZ contains a 3 × 3 Z-score array and its voxel/frequency coordinates. It contains no raw-value array. Raw values may be calculated internally to derive Z-scores, but unrequested values are not returned.

06 / STRUCTURED OUTPUT

Read one metric or the complete result.

GET /v1/jobs/JOB_ID
GET /v1/jobs/JOB_ID/analytics?metric=surface.absolute_power.band&value=z
GET /v1/jobs/JOB_ID/analytics?metric=surface.coherence.band&metric=source.loreta.power
GET /v1/jobs/JOB_ID/analytics

These requests require your Bearer key. Repeat metric and value to choose several. Omit both to return every computed measurement in one JSON response, including voxel arrays. This endpoint only retrieves results already computed in that job. It does not rerun analysis; missing measurements or value variants return 422. Submit a new selection against the same recording when you need additional computations.

Values are split into surface.raw, surface.z, and each source method’s raw/z objects. Surface paths continue as measurement → axis → cell → column. Regional source paths continue as power/coherence → region/pair → band. Example structure with illustrative numbers:

{
  "schema_version": "2.0",
  "recording_id": "RECORDING_ID",
  "artifact_job_id": "ARTIFACT_JOB_ID",
  "job_id": "JOB_ID",
  "surface": {
    "raw": { "absolute_power": { "band": { "FP1-LE": { "Alpha": 12.4 } } } },
    "z":   { "absolute_power": { "band": { "FP1-LE": { "Alpha": 0.7 } } } }
  },
  "source": {
    "loreta": {
      "reference": "average",
      "calibration": "reconstructed",
      "raw": { "power": { "7 L": { "alpha_1": 8.2 } } },
      "z":   { "power": { "7 L": { "alpha_1": -0.3 } } }
    }
  }
}

Actual responses also include the normalized selection, age/bin, condition, reference, retained intervals, processing rate, pipeline and asset versions, and applicable method limitations. Raw-only responses omit z values; Z-score-only responses omit raw values. Unavailable numeric values are JSON null, never fabricated zeros.

File downloads and one-file delivery

Use the job manifest’s exact download URLs, SHA-256 and byte counts. For large voxel results, NPZ or ZIP is more compact than expanded JSON. Read NPZ with numpy.load(..., allow_pickle=False); binary arrays preserve NaN where values are undefined. ZIP JSON references its sibling NPZ. Selective JSON retrieval expands the requested voxel arrays into source.current_density.raw/z and includes coordinate arrays.

Python client

from taraaz.client import Client

client = Client(BASE_URL, API_KEY)
catalog = client.metrics(montage="LE")
job = client.analyze(
    recording_id, artifact_job_id,
    idempotency_key="alpha-z-001",
    outputs=[{"metric": "surface.absolute_power.band", "values": ["z"]}],
)
# Wait until client.job(job["id"])["state"] == "succeeded".
result = client.analytics(job["id"], metrics=["surface.absolute_power.band"], values=["z"])
client.close()

07 / CONNECTION RECOVERY

Resume from acknowledged work.

• Persist the recording ID, original bytes and idempotency keys locally. Retry the same creation/submission payload with the same key after a timeout.
• Use GET /v1/recordings/{id}?after=-1&limit=256 to inspect acknowledged chunks. Continue from the last sequence until a page is empty. Resend only missing chunks.
• An identical chunk retry returns duplicate: true. A changed payload or offset under the same sequence returns 409.
• Poll jobs with If-None-Match, honor Retry-After, or read event cursors with GET /v1/jobs/{id}/events?after=EVENT_ID.
• Resume file downloads with Range: bytes=OFFSET- and If-Range set to the file’s quoted SHA-256 ETag. Verify the complete checksum afterward.
• The selective JSON endpoint supports ETags and optional gzip. Its responses do not support byte-range resumption; use the immutable manifest files when resuming matters.

08 / REFERENCES & NORMS

Interpret each result in context.

Surface and voxel current density: choose LE or AVE. LE requires measured A1 and A2 channels, or input explicitly marked as already linked-ear referenced. Surface coherence and phase lag are exposed only for LE. Regional LORETA/eLORETA: internally average-referenced regardless of the requested montage; the result states reference: average.

Z-scores use the recording’s age and EC/EO condition. Ages must be at least 1 and below 100. Supported bins are 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15-16, 17-19, 20-24, 25-29, 30-34, 35-44, 45-99. Age is floored to whole years for bin selection. Ages 45–99 share one bin. A Z-score applies the stored metric-specific transform, subtracts its normative mean and divides by its normative standard deviation; it is not necessarily (raw − mean) / SD in untransformed units.

The bundled norms are reconstructed from reference exports. Regional source absolute scaling and LORETA coherence retain calibration limitations. eLORETA power uses transferred norms; eLORETA coherence has no Z-score norms. Current density reports calibrated source power, not physical vector currents. These distinctions apply to interpretation and comparison with other systems.

09 / ERRORS & COMPATIBILITY

Explicit failures, predictable selections.

Jobs move through queued, running, succeeded or failed. Inspect the job error after failure. A failed or ineligible artifact dependency never falls back to unchecked EEG.

Existing clients may continue sending measures: ["surface", "current_density", "loreta", "eloreta"]. They keep their original separate files and {raw,z} cells. Do not combine measures with outputs. The new organized schema, selective retrieval and ZIP option require outputs. Unknown selectors are never ignored.