Developers

API Documentation

v1

A versioned, read-only HTTP API for pulling your own Eclipse session data into tools you control.

A versioned, read-only HTTP API that lets a server-side integration you control pull Eclipse session data — your own with a personal key, or your team's athletes' with a team key — sessions, processing status, rep/window-level EMG & IMU features, AI reports, and file metadata/downloads.

Server-side only. API keys are access tokens with the same power as a password for the data they read: a personal key reads your own data; a team key reads every athlete's roster and session list, and every consenting athlete's sensor data, on the team. Never embed a key in a browser page, mobile app bundle, or any client distributed to others — anyone who extracts it can read that data until you revoke it. Call this API from your own backend, script, or CI job, and forward only the results you need to any client you build.

Getting a key

This is how to get a personal key. Team admins create team keys in Team Settings instead — see Team API keys.

  1. Sign in to the portal and go to Account Settings.
  2. In the API Keys section, click Create New Key.
  3. Name the key, choose the scopes it needs, choose an expiry (default 90 days, maximum 365), and confirm with your password (and authenticator code, if you have two-factor authentication enabled).
  4. Copy the plaintext key immediately — it is shown exactly once and cannot be retrieved again. If you lose it, revoke it and create a new one.

You can have at most 10 active (non-revoked, non-expired) keys at a time. Revoking a key is immediate and does not require your password.

Team API keys

A team key reads the sessions of the athletes on a team, so a team can pull its data into Power BI, Tableau, or a script without each athlete creating a key.

Who creates them, and where. Any admin of the team can create, list, and revoke any of the team's keys: sign in, open Team Settings, and use the API Keys section for the team. Creation needs the admin's current password, plus an authenticator code if they have two-factor authentication enabled. A team has at most 10 active keys. Expiry defaults to 90 days and is at most 365. The scopes are the same four as for personal keys: sessions:read, features:read, reports:read, files:read. As with a personal key, the plaintext is shown exactly once.

Prefix. A team key starts with ecl_team_ (for example ecl_team_v1_<random>). Send it as a bearer token exactly like a personal key. A team key works on every /api/v1 endpoint; GET /api/v1/athletes works only with a team key.

What a key reads. A team key can see a session when the session's owner is currently an athlete on the key's team. That covers every session of a current athlete, including sessions recorded before they joined the team. Sessions of the team's admins are not included, and nothing outside the key's team is. A session that is not visible to the key returns 404 not_found, the same as a session that does not exist.

When an athlete leaves the team or becomes an admin, all of their sessions stop being visible to the key at once. updated_after sync does not report this; compare your stored athletes against GET /api/v1/athletes to detect departures and delete their data if your policy requires it.

athleteId. With a team key, each session carries athleteId, and GET /api/v1/athletes returns an id for each athlete. Both are an opaque identifier for the athlete, stable for as long as the athlete exists; do not treat it as a user id. Use it to group sessions by athlete and to pass back as athlete_id.

GET /api/v1/athletes

Team keys only; requires sessions:read. Lists every athlete on the team, ordered by joinedAt and then id. It has no pagination and no meta. A personal key gets 403 forbidden (This endpoint requires a team API key.).

{
  "data": [
    {
      "id": "uuid",
      "fullName": "Alex Rivera",
      "position": "Midfielder",
      "joinedAt": "2026-01-10T09:00:00.000Z"
    }
  ]
}

fullName and position may be null.

GET /api/v1/athletes and GET /api/v1/sessions list everyone on the team, with metadata only, whether or not the athlete has given sensor data consent.

Filtering sessions by athlete

With a team key, GET /api/v1/sessions also accepts athlete_id=<id> (an id from GET /api/v1/athletes) to list one athlete's sessions. A value that is not a UUID returns 400 bad_request (athlete_id must be a UUID.). A valid UUID that is not a current athlete on the team returns 200 with data: [], not 404. A personal key that sends athlete_id gets 400 bad_request (athlete_id is only accepted with a team API key.).

Sensor data consent is checked for the athlete who owns the session, not for whoever created the key:

EndpointAthlete has not given consent
GET /sessions and GET /athletesThe athlete is listed; metadata only.
GET /sessions/:idAnswers with processing: null.
Features, report, files, download, and the per-session exports (/sessions/:id/exports/summary, /sets, /timeseries)403 sensor_consent_required (The athlete who owns this session has not given sensor data consent. Files, features and reports are unavailable.). A session that is not on the team returns 404 not_found first.
GET /exports/summaryThe athlete's rows are left out. A page can therefore hold fewer rows than limit, while nextCursor and hasMore follow the underlying session page, so keep paging until hasMore is false. Columns are unchanged and export_schema_version stays 1.

If the consent lookup itself fails, the API returns 500 internal_error — retry the request.

Detailed reports

GET /sessions/:id/report?type=detailed is never available to a team key. Once the session resolves (it is on the team and its athlete has given consent), the response is the same 404 not_found as for "no completed report of this type". A session that is not on the team gets the Session not found. 404, and an athlete without consent gets the 403 sensor_consent_required first.

Lifecycle

A team key authenticates only while the admin who created it is still an admin of the team. When that admin leaves the team, is demoted, or deletes their account, the key stops working at once with 401 unauthorized (the same response as a revoked key) and is marked revoked. Deleting the team deletes its keys. Any admin of the team can revoke any key from Team Settings, and revoking needs no password.

Rate limit

Each team key has its own limit of 60 requests/minute, not shared with any other key. The headers and the 429 body are the same as for a personal key. Each request writes one usage event for the key; usage events are kept for 90 days.

Authentication

Send the key as a bearer token on every request:

Authorization: Bearer ecl_live_v1_<random>

Requests without a valid, unexpired, unrevoked key are rejected with 401 unauthorized. There is no cookie- or session-based authentication for /api/v1 — it is exclusively for bearer-token clients.

Scopes

Each key is created with one or more scopes. A request fails with 403 forbidden if the key doesn't have the scope an endpoint requires.

ScopeGrants
sessions:readList sessions; read session metadata and processing status
features:readRead rep- and window-level EMG/IMU features
reports:readRead the latest completed AI-generated report
files:readList uploaded file metadata; mint short-lived download links

Keys never inherit coach, organization-admin, or session-share access. A personal key reads only the data owned by the account that created it. A team key reads only the sessions of athletes currently on its own team (see Team API keys). Scope never widens either.

Response envelope

Successful responses:

{ "data": /* object or array */, "meta": { "nextCursor": "...", "hasMore": true } }

meta is only present on paginated list endpoints (and carries extra fields on the features endpoint — see below).

The analyst export endpoints are the exception: with format=csv they answer with text/csv; charset=utf-8 (a UTF-8 file starting with a byte-order mark), not the JSON envelope. Errors are still the JSON error envelope below.

Errors:

{ "error": { "code": "not_found", "message": "..." } }

code is one of unauthorized, forbidden, sensor_consent_required, not_found, bad_request, rate_limited, internal_error. Error messages never include database details, storage paths, or other internal identifiers. An ID that doesn't exist and an ID that belongs to someone else (another user, or for a team key a session outside the team) both return the same 404 not_found — the API never reveals whether a resource exists for someone else.

Every response includes Cache-Control: private, no-store and X-Request-Id; include the latter when reporting an issue.

Errors

StatusCodeMeaning
400bad_requestMalformed query parameter, body, or cursor
401unauthorizedMissing, malformed, unknown, revoked, or expired key; for a team key, also when its creator is no longer an admin of the team
403forbiddenKey is valid but lacks the required scope; or a personal key on GET /api/v1/athletes (This endpoint requires a team API key.). A team key on an endpoint that does not accept team keys gets This endpoint does not accept team API keys.; no endpoint does today
403sensor_consent_requiredThe key's owner has not given (or has withdrawn) sensor data consent; for a team key, the athlete who owns the session. Returned by every files:read, features:read and reports:read endpoint. GET /sessions/{id} still answers, with processing: null. If the consent check itself fails, the API returns 500 internal_error instead — retry the request
404not_foundResource doesn't exist, or this key can't see it (a personal key sees its owner's sessions; a team key sees its athletes' sessions)
429rate_limitedPer-key rate limit exceeded — see Retry-After
500internal_errorUnexpected server error

Rate limits

Each key is limited to 60 requests/minute, enforced independently per key. Every response carries:

RateLimit-Limit: 60
RateLimit-Remaining: <n>

A 429 additionally includes Retry-After: <seconds>. Limits reset on a fixed one-minute window per key; there is no cross-key or account-wide pooling.

Pagination

List endpoints return an opaque nextCursor string — treat it as a black box; don't construct or parse it yourself. Pass it back as the cursor query parameter to get the next page. hasMore tells you whether another page exists.

  • Default page size is 100 items; pass limit (1–500) to change it.
  • GET /api/v1/sessions also accepts updated_after (ISO-8601) to fetch only sessions changed since a point in time, ordered on the same (updated_at, id) axis as the cursor — safe to use for incremental sync. Note that updated_at only advances on session-record edits (e.g. renaming a session), not when it's reprocessed or gets a new report, since those touch child tables, not the session row itself.
  • GET /api/v1/sessions/:id/features pins pagination to one processing run: the first page selects the most recently completed (or partial) run and returns its ID in meta.processedSessionId; every subsequent page for that cursor stays pinned to that same run, so a reprocessing job started mid-sync can never mix rows from two different runs into one paginated result.
  • A cursor that fails to decode returns 400 bad_request rather than silently starting over.

Endpoints

All paths are relative to https://www.eclipseperf.com.

GET /api/v1/athletes

Team keys only; requires sessions:read. See Team API keys.

GET /api/v1/sessions

Requires sessions:read. Lists your sessions (with a team key, the team's athletes' sessions), ordered oldest-to-newest by (updated_at, id).

Query parameters: cursor, limit, updated_after, and athlete_id (team keys only). With a team key each session also carries athleteId (see Team API keys).

{
  "data": [
    {
      "id": "uuid",
      "name": "Morning Training",
      "description": null,
      "workoutType": "Squats",
      "startedAt": "2026-01-15T08:00:00.000Z",
      "endedAt": "2026-01-15T08:30:00.000Z",
      "createdAt": "2026-01-15T08:31:00.000Z",
      "updatedAt": "2026-01-15T08:31:00.000Z"
    }
  ],
  "meta": { "nextCursor": "eyJ1IjoiMjAyNi...", "hasMore": true }
}

With a team key each object also has "athleteId": "<uuid>".

GET /api/v1/sessions/:id

Requires sessions:read. Returns session metadata plus the latest processing run summary (or null if the session hasn't been processed yet, or if the key's owner — for a team key, the session's athlete — has no current sensor data consent).

{
  "data": {
    "id": "uuid",
    "name": "Morning Training",
    "description": null,
    "workoutType": "Squats",
    "startedAt": "2026-01-15T08:00:00.000Z",
    "endedAt": "2026-01-15T08:30:00.000Z",
    "createdAt": "2026-01-15T08:31:00.000Z",
    "updatedAt": "2026-01-15T08:31:00.000Z",
    "processing": {
      "id": "uuid",
      "pipelineVersionId": "uuid",
      "status": "completed",
      "startedAt": "2026-01-15T08:31:05.000Z",
      "completedAt": "2026-01-15T08:31:40.000Z",
      "durationMs": 1800000,
      "emgSampleCount": 540000,
      "imuSampleCount": 108000,
      "bleQuality": { "...": "..." },
      "qualityFlags": { "...": "..." },
      "createdAt": "2026-01-15T08:31:05.000Z",
      "updatedAt": "2026-01-15T08:31:40.000Z"
    }
  }
}

GET /api/v1/sessions/:id/features

Requires features:read. Returns rep- or window-level features for the session's latest completed/partial processing run.

Query parameters: level (required — windows or reps), leg (optional — left, right or unknown), cursor, limit.

leg pins the first page to that leg's latest run; later pages follow the cursor and stay on that run. Without it the behaviour is unchanged: the first page selects the session's most recent run, which for a two-sleeve session means either leg. An invalid value returns 400 bad_request (leg must be 'left', 'right' or 'unknown'.).

{
  "data": [
    {
      "windowIndex": 0,
      "leg": "left",
      "startTimeMs": 0,
      "endTimeMs": 500,
      "emgRms": [0.12, 0.31, 0.28, 0.09],
      "emgEnvelope": [0.10, 0.27, 0.24, 0.08],
      "emgMedianFreq": [88.2, 94.1, 91.7, 85.3],
      "imuMagnitudeMean": 1.02,
      "imuIntensity": 0.44,
      "extra": null,
      "createdAt": "2026-01-15T08:31:40.000Z"
    }
  ],
  "meta": {
    "nextCursor": "eyJwIjoiMTIzNC...",
    "hasMore": true,
    "processedSessionId": "uuid",
    "level": "windows"
  }
}

emgRms, emgEnvelope, emgMedianFreq, etc. are 4-element arrays indexed by EMG channel (0 = Biceps Femoris / Outer Hamstring, 1 = Vastus Lateralis / Outer Quad, 2 = Vastus Medialis / Inner Quad, 3 = Semitendinosus / Inner Hamstring). Any element may be null when that channel's data was absent or low-quality for that window/rep. level=reps additionally includes durationMs, emgMeanRectified, emgOnsetMs, emgOffsetMs, emgEmdMs, imuPeakMagnitude, phaseData, and setIndex (the 0-based detected set the rep belongs to, or null). Both levels include leg (left, right or unknown).

startTimeMs / endTimeMs mean different things at the two levels:

  • Windows: milliseconds since the file's first EMG sample, so window 0 starts at 0 (roughly file_time_s × 1000 in the analyst time-series export).
  • Reps: the sensor's own milliseconds since power-on — the same clock as device_time_ms in the time-series export (for example startTimeMs: 512340, endTimeMs: 512840). This clock is not comparable between the two sleeves of a session.

If the session has no completed or partial processing run yet, data is [], meta.processedSessionId is null, and meta.hasMore is false.

GET /api/v1/sessions/:id/report

Requires reports:read. Returns the latest completed AI report for the session.

Query parameters: type — simple (session_analysis, default). detailed is reserved for Eclipse-internal use and always returns 404 not_found for external API keys, identical to the response when no report of that type exists.

{
  "data": {
    "id": "uuid",
    "reportType": "session_analysis",
    "status": "completed",
    "content": { "dataAnalysis": { "...": "..." }, "narrative": { "...": "..." }, "metadata": { "...": "..." } },
    "generatedAt": "2026-01-15T08:32:00.000Z",
    "createdAt": "2026-01-15T08:32:00.000Z",
    "updatedAt": "2026-01-15T08:32:00.000Z"
  }
}

Returns 404 not_found if no completed report of that type exists yet (including while one is still generating). content is never null for a completed report.

GET /api/v1/sessions/:id/files

Requires files:read. Lists uploaded file metadata — never a storage path.

{
  "data": [
    {
      "id": "uuid",
      "fileName": "left-sleeve.eclbin",
      "fileSize": 1048576,
      "fileType": "application/octet-stream",
      "leg": "left",
      "uploadedAt": "2026-01-15T08:05:00.000Z"
    }
  ]
}

GET /api/v1/sessions/:id/files/:fileId/download

Requires files:read. Mints a 60-second signed URL for downloading the raw file from storage.

{ "data": { "url": "https://.../session-files/...", "expiresInSeconds": 60 } }

This is a GET, not a POST, because minting a short-lived URL has no persistent side effect on the data — it keeps the whole /api/v1 surface read-only. Each call writes a dedicated, synchronous audit record before the URL is returned; if the signed URL can't be created or that audit write fails, the endpoint returns 500 internal_error and never includes a URL in the response body. Because this issuance audit is separate from the general per-request usage event every route writes, a single successful download call produces two usage-event rows by design.

Revoking a key does not retroactively invalidate a signed URL that was already issued. The URL keeps working for the remainder of its (at most 60-second) lifetime even after revocation — treat any URL you receive as sensitive for that short window.

Analyst exports

Flat CSV/JSON tables for Power BI, Tableau and similar tools. Column definitions are in docs/analyst-exports/FIELD_DICTIONARY.md; a walkthrough for loading them is in docs/analyst-exports/README.md.

Like every other /api/v1 endpoint that reads sensor data, these return 403 sensor_consent_required unless the key's owner has given sensor data consent. With a team key, the per-session exports check the session's athlete, and GET /api/v1/exports/summary leaves that athlete's rows out instead (see Consent, per athlete).

GET /api/v1/sessions/:id/exports/summary and GET /api/v1/sessions/:id/exports/sets

Require features:read. Query parameter: format — json (default) or csv; anything else returns 400 bad_request. summary returns one row for the session; sets returns one row per leg and detected set.

JSON. summary returns data as a single object (the session's row); sets returns data as an array of rows:

{ "data": { "export_schema_version": 1, "session_id": "uuid", "...": "..." }, "meta": { "schemaVersion": 1, "columns": ["export_schema_version", "session_id", "..."] } }
{ "data": [ { "export_schema_version": 1, "session_id": "uuid", "leg": "left", "...": "..." } ], "meta": { "schemaVersion": 1, "columns": ["export_schema_version", "session_id", "..."] } }

CSV is text/csv; charset=utf-8 with a UTF-8 BOM, served as eclipse-session-{id}-summary.csv or eclipse-session-{id}-sets.csv. A session that does not exist or is not visible to your key (not yours, or for a team key not on the team) returns 404 not_found.

GET /api/v1/exports/summary

Requires features:read. One summary row per session, oldest-to-newest by (updated_at, id).

With a team key, rows of athletes without sensor consent are left out, so a page can hold fewer than limit rows; keep paging until hasMore is false.

Query parameters: cursor, limit (1–50, default 25; larger values are clamped to 50, and a value below 1 or non-numeric returns 400 bad_request), updated_after (ISO-8601; invalid returns 400 bad_request), format (json or csv). An invalid cursor returns 400 bad_request.

JSON: { "data": [rows], "meta": { "nextCursor": "...", "hasMore": true, "schemaVersion": 1, "columns": [...] } }.

CSV (eclipse-sessions-summary.csv) carries the paging in response headers instead: X-Next-Cursor (an empty string on the last page) and X-Has-More (true / false). Pass the cursor back as cursor.

GET /api/v1/sessions/:id/exports/timeseries

Requires files:read. Builds one CSV per sample stream of one sleeve file and returns short-lived signed URLs for it.

Query parameters (both required): fileId (from GET /api/v1/sessions/:id/files) and stream (emg or imu).

{
  "data": {
    "schemaVersion": 1,
    "sessionId": "uuid",
    "fileId": "uuid",
    "leg": "left",
    "stream": "emg",
    "rowCount": 1000000,
    "declaredRateHz": 1000,
    "originDeviceTimeMs": 512340,
    "clock": { "estimatedUtcOffsetMs": 1768463487660, "spreadMs": 18, "packetCount": 480000 },
    "columns": ["session_id", "athlete_name", "started_at_utc", "leg", "stream_record_index", "device_time_ms", "..."],
    "parts": [
      { "part": 1, "rowCount": 400000, "url": "https://.../session-files/..." },
      { "part": 2, "rowCount": 400000, "url": "https://.../session-files/..." },
      { "part": 3, "rowCount": 200000, "url": "https://.../session-files/..." }
    ],
    "expiresInSeconds": 60
  }
}
  • originDeviceTimeMs is the device_time_ms that file_time_s is measured from (the file's earliest EMG sample, or its earliest IMU sample if the file has no EMG).
  • clock.estimatedUtcOffsetMs gives est_utc = device_time_ms + estimatedUtcOffsetMs (Unix-epoch ms); it is null when the file has no phone timestamps, in which case est_utc is blank. In the example above, 512340 + 1768463487660 is 2026-01-15T08:00:00Z. clock.spreadMs is a jitter indicator, not an error bound. clock.packetCount counts EMG and IMU packets together. declaredRateHz is the header's sample rate for the stream.
  • Each part holds at most 400,000 rows (about 6.7 minutes of EMG) and starts with the header row. Append the parts in part order. sessionId and fileId are the stored ids.
  • Download every parts[].url within expiresInSeconds (60). Revoking a key does not invalidate a URL already issued.
  • The first call for a file can take tens of seconds while it is built. The parts are cached in storage beside the session's files and reused, so later calls are fast.
  • A successful call writes the same extra synchronous download_issued audit row as a file download, before the response is returned. If the export cannot be built or signed, or the audit write fails, the endpoint returns 500 internal_error and never includes a URL.
  • Errors: 400 bad_request — fileId is required., stream must be 'emg' or 'imu'., or Time-series export is only available for .eclbin files. (non-.eclbin files); 404 not_found — File not found. (also when the session is deleted while the export is being built).
curl -H "Authorization: Bearer ecl_live_v1_..." \
  "https://www.eclipseperf.com/api/v1/sessions/<session-id>/exports/timeseries?fileId=<file-id>&stream=emg"

Key rotation & versioning

Every token embeds a version, e.g. ecl_live_v1_<random> (personal) or ecl_team_v1_<random> (team). If Eclipse rotates the server-side signing secret, new keys are issued under a new version (ecl_live_v2_..., ecl_team_v2_...) while existing v1 keys keep working until they individually expire or are revoked — you do not need to take any action when a rotation happens. Your key's prefix (e.g. ecl_live_v1_AbCdEfGh) is shown in Account Settings (Team Settings for a team key) so you can identify which key is which without ever seeing the full secret again.

curl examples

# List sessions
curl -H "Authorization: Bearer ecl_live_v1_..." \
  "https://www.eclipseperf.com/api/v1/sessions?limit=20"

# Incremental sync since a point in time
curl -H "Authorization: Bearer ecl_live_v1_..." \
  "https://www.eclipseperf.com/api/v1/sessions?updated_after=2026-01-01T00:00:00Z"

# Session detail
curl -H "Authorization: Bearer ecl_live_v1_..." \
  "https://www.eclipseperf.com/api/v1/sessions/<session-id>"

# Team key: the team's athletes, then one athlete's sessions
curl -H "Authorization: Bearer ecl_team_v1_..." \
  "https://www.eclipseperf.com/api/v1/athletes"
curl -H "Authorization: Bearer ecl_team_v1_..." \
  "https://www.eclipseperf.com/api/v1/sessions?athlete_id=<athlete-id>"

# Window-level features, first page
curl -H "Authorization: Bearer ecl_live_v1_..." \
  "https://www.eclipseperf.com/api/v1/sessions/<session-id>/features?level=windows"

# Latest report
curl -H "Authorization: Bearer ecl_live_v1_..." \
  "https://www.eclipseperf.com/api/v1/sessions/<session-id>/report"

# File metadata, then a download link
curl -H "Authorization: Bearer ecl_live_v1_..." \
  "https://www.eclipseperf.com/api/v1/sessions/<session-id>/files"
curl -H "Authorization: Bearer ecl_live_v1_..." \
  "https://www.eclipseperf.com/api/v1/sessions/<session-id>/files/<file-id>/download"

Support

Questions or suspect a leaked key? Revoke it immediately — a personal key from Account Settings, a team key from Team Settings — then contact support with the X-Request-Id from any affected response.