Skip to content
AiKYNETIX

Create a session and enqueue inference

POST
/api/sessions/
curl -X POST https://api.ai.aikynetix.app/api/sessions/ \
  -H 'Authorization: Bearer aik_yourPartnerTokenHere' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "5c836d7d-3301-49df-bfa0-9cff0550fd0e",
    "activity": "running",
    "exercise": "Treadmill",
    "video_url": "https://media.ai.aikynetix.app/.../clip.source.mp4",
    "client": "f6d52e64-3aa3-4a26-bac2-0fc9d718448d",
    "camera_view": "side"
  }'

Records a new Session pointing at the just-uploaded video, debits the team’s session quota, and enqueues the analysis pipeline. Pass id if you reserved one via POST /api/sessions/upload-intent/ (recommended — keeps the storage object key and the Session.id consistent). activity is required; exercise selects the specific movement within it (e.g. Treadmill for running). camera_view (side / front / back) tells the pose pipeline which analyzers to run. client is the athlete UUID — without it, body-aware adjustments fall back to defaults. Returns 201 with the new Session in pending status; poll GET /api/sessions/<id>/ until status == 'completed'.

402 when quota is exhausted or the subscription is suspended — no debit happens, the upload object stays orphaned until the team-wide GC. 503 enqueue_failed if the quota debit succeeded but the task broker was unreachable; safe to retry.

Auth: team-scoped — reachable with a partner aik_… API key. 403 if the caller has no active team selected (a transient state, e.g. mid team-switch).

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
object
id

The session UUID reserved by POST /api/sessions/upload-intent/. Pass it back here so the row id matches the storage object key. Optional for ad-hoc creation without an upload-intent roundtrip.

string format: uuid
activity
required

Activity family — running, walking, jumps, weightlifting, agility, mobility, fencing, ergonomics. Required.

  • running - Running
  • walking - Walking
  • jump - Vertical Jump
  • weightlifting - Weightlifting
  • mobility - Mobility Assessment
  • workspace_wellness - Workspace Wellness
  • agility - Agility
  • fencing - Fencing
  • cycling - Cycling
  • tennis - Tennis
  • padel - Padel Tennis
  • bowling - Bowling
  • baseball - Baseball
  • football - Football
  • badminton - Badminton
  • cricket - Cricket
  • basketball - Basketball
  • scuba_diving - Scuba Diving
  • ice_hockey - Ice Hockey
  • american_football - American Football
  • fri - Falls Risk Indicator
string
Allowed values: running walking jump weightlifting mobility workspace_wellness agility fencing cycling tennis padel bowling baseball football badminton cricket basketball scuba_diving ice_hockey american_football fri
exercise

Specific movement (e.g. Treadmill, Back Squat). Pick from GET /api/exercises/?activity=.... Optional but strongly recommended — without it the analyzer uses activity-default settings and metrics may be less specific.

string
<= 80 characters
video_url
Any of:
string format: uri
<= 1000 characters
client

UUID of the Client this session is about. Recommended — without it body-aware metric adjustments fall back to defaults.

string format: uuid
nullable
handedness

Optional dominant-hand hint (right by default). Read by handedness-aware analyzers — fencing maps raw left/right pose-landmark sides to semantic front/rear by lead leg; tennis and bowling map them to dominance-relative keys so a left-handed forehand (or left-handed bowler) reads identically to the right-handed case. Silently ignored by activities whose analyzers don’t read this field.

  • right - Right-handed
  • left - Left-handed
string
Allowed values: right left
camera_view

Camera plane for the recording. side (sagittal, default) runs the stride / GCT / speed / sagittal-angle analyzer. front / back swap to the frontal analyzer (pelvic drop, hip adduction, step width, trunk sway, L/R asymmetry). When exercise is set, the value must be one of the pair’s supported views — an unsupported plane is a 400 (#1829). See views_by_exercise in GET /api/exercises/?activity=… for each pair’s supported set.

  • side - Side
  • front - Front
  • back - Back
string
Allowed values: side front back
scuba_session_meta

Scuba diving session-meta sidecar — required when activity == scuba_diving, silently ignored for every other activity. Validates side_involved, condition, arms_engaged, and the optional clinical fields (Borg CR-10, fin model, calibration scale bar). Stored on Session.meta.scuba so the analyzer can read it via the X-Aikmodels-Contract 3→4 plumbing (P0.5). See project_context/architecture/DESIGN_SCUBA_V1.md §“Session metadata sidecar”.

object
side_involved
required
One of:
  • L - Left
  • R - Right
string
Allowed values: L R
condition
required

§5.2 condition tag. Used for cohort tagging on the dashboard + the report PDF cover. Must match the trial design — not derived from other fields, because the same diver shoots multiple conditions per session.

  • control_no_arms - Control — no arms
  • control_with_arms - Control — with arms
  • transtibial - Transtibial
  • transfemoral - Transfemoral
string
Allowed values: control_no_arms control_with_arms transtibial transfemoral
arms_engaged
required

Confound flag (§4.6). True when the diver was sculling / using arms for propulsion during the bout. Surfaces in the report so coaches know to filter symmetry numbers.

boolean
fin_model

Fin model — free-form (manufacturer + model).

string
"" <= 128 characters
fin_stiffness

Fin stiffness. Free-form: either a qualitative grade (soft / medium / stiff) or a numeric string with units (12 N·m/rad). Analyzer doesn’t consume it in V1; captured for the report + future fin-deflection v2 work.

string
"" <= 64 characters
borg_residual_post_bout

Borg CR-10 perceived exertion (residual side), 0–10.

integer
nullable <= 10
borg_sound_post_bout

Borg CR-10 perceived exertion (sound side), 0–10.

integer
nullable <= 10
calibration_scale_bar_m

Length of the in-frame calibration scale bar (§6.1), in metres. Optional — without it, body-aware distance metrics use body_scale_px(ctx) per the standard fallback.

number format: double
nullable
workstation_assessment

Damian’s 12-question ergonomics survey payload — required for the workspace_wellness:Ergonomics Assessment exercise, silently ignored for every other activity/exercise. Gated on the (activity, exercise) pair, so a future workspace_wellness exercise does not inherit the mandatory survey. Lands on Session.meta.workstation_assessment after validation. See #303 for the full spec + biomech rationale.

object
setup
required

Reusable workstation setup — posture + the six desk/seat/screen geometry measurements (Damian Q2–Q7). Snapshotted onto the session and persisted on the client for reuse.

object
posture
required

Anton’s sit/stand toggle. Drives which measurement fields are required (seat-related fields are seated-only). When both apply to the subject’s workstation, the spec is to upload two separate sessions per CEO routing — one row per posture.

  • seated - Seated
  • standing - Standing
string
Allowed values: seated standing
measurements_cm
required

Damian Q2–Q7. Six desk/seat/screen geometry measurements; three are seated-only.

object
desktop_height
required

Damian Q2. Desk-top height in cm (floor → desk surface).

number format: double
>= 0.1 <= 300
seat_top_height

Damian Q3. Seat-top height in cm (floor → top of seat pan). Required when posture is seated.

number format: double
nullable >= 0.1 <= 300
seat_pan_depth

Damian Q4. Seat-pan depth in cm — measured from the point where the back rest meets the seat pan to the front edge of the seat pan. Required when posture is seated.

number format: double
nullable >= 0.1 <= 300
back_rest_height

Damian Q5. Back-rest height in cm (seat pan → top of back rest). Required when posture is seated.

number format: double
nullable >= 0.1 <= 300
eye_level_height
required

Damian Q6. Eye-level height in cm from the floor. Carries the seated OR standing variant depending on posture — the frontend UI prompt switches wording, the field value lands here either way.

number format: double
>= 0.1 <= 300
screen_top_height
required

Damian Q7. Top-of-screen height in cm from the floor. Same seated/standing variant pattern as eye_level_height.

number format: double
>= 0.1 <= 300
anthropometry

Subject anthropometry (Damian Q1, physical height). Optional — only sent when the client profile lacks a height; the create path writes it back to Client.height_cm.

object
physical_height_cm

Damian Q1. Subject’s physical height in cm (floor → top of head). Asked once when the client profile lacks a height; written back to Client.height_cm on session create. Omit when the profile already carries the height — the analyzer reads it from there.

number format: double
nullable >= 0.1 <= 300
pain
required

Damian Q8–Q9. Pain assessment + body-part dropdown.

object
has_pain
required

Damian Q8. True if the subject reports pain/discomfort at the workstation.

boolean
body_part
One of:
  • head_neck - Head / Neck
  • shoulder_upper_back - Shoulder / Upper Back
  • torso - Torso
  • hip_lower_back - Hip / Lower Back
  • lower_body - Lower Body
  • arms_wrists - Arms / Wrists
string
Allowed values: head_neck shoulder_upper_back torso hip_lower_back lower_body arms_wrists
sit_duration_min
required

Damian Q10. How long the subject sits at the desk without a posture change, in minutes. Damian’s biomech grounding: stretches >30 min create MSK tension (per occupational-health research). The analyzer-side risk score weights this alongside the pose readings.

integer
<= 480
posture_media
required

Damian Q11. Image or short video showing the workstation subject in their typical posture. The uploaded URL comes from the second presign returned by the upload-intent endpoint.

object
url
required

Canonical URL of the uploaded posture media (image or short video). Returned as posture_media.public_url by the upload-intent endpoint. Validated against the storage public-origin allowlist — the URL is later fetched by the ergonomist render path + the analyzer, so accepting an arbitrary host would be an SSRF gadget.

string format: uri
>= 1 characters
kind
required

Whether the upload is a still image or a short (1–3 s) video. Both are accepted per Damian’s spec — coaches at the Pegel Padel pilot site default to image; short video is the fallback when the static frame is ambiguous (e.g. mid-stride).

  • image - Image
  • video - Video
string
Allowed values: image video
name

Optional coach-assigned label for the session (#584), shown in the journal, the player header and shared views — handy for telling apart same-day, same-exercise sessions of one participant (e.g. Kevin – Baseline – Side View). Editable later via PATCH /api/sessions/{id}/. Omit for none.

string
<= 120 characters
trim

Optional time range to trim the clip to, in seconds ({start_s, end_s}). Applied server-side during normalization, so the cut is accurate at any source frame rate. Omit to process the full clip.

object
start_s
required

Trim start in seconds from the clip origin.

number format: double
end_s
required

Trim end in seconds; must be greater than start_s.

number format: double
blur_face

Opt-in face anonymisation. true → the subject’s face is blurred in the analysed (annotated) video — the artifact that is stored long-term, shown in the player and shared with the client. Metrics are unaffected (analysis runs on the clean frames first). The raw upload itself is NOT anonymised. Omit for the default (no blur).

boolean
treadmill_incline_deg

Treadmill incline in degrees for running / walking treadmill sessions (0 = overground / level belt, the default). Positive = uphill, negative = decline treadmill. The analyzer re-references the foot-strike contact angle to the belt plane (legacy compute_fs_angles) and reports signed elevation change (gain uphill / loss on a decline), so an inclined run reads its true strike angle rather than one inflated by the slope. Stored on Session.meta.treadmill_incline_deg and forwarded to aikmodels. Silently ignored for non-gait activities. Omit (or 0) for overground.

number format: double
>= -30 <= 30
lang

Coach’s platform UI language (en / ru / es) at upload time. Snapshotted onto Session.meta.lang and forwarded to aikmodels so the joint-angle chips baked onto the annotated video render in that language (#1194); the angle values (°) are unchanged. Draw-stage only — no metric value depends on it. Omit (or en) for English, the default. Because the annotated mp4 is rendered once at processing, this reflects the language at that time; switching the UI language later does not retro-localize an already-rendered video.

  • en - English
  • ru - Русский
  • es - Español
string
Allowed values: en ru es
approach_step_count

Bowling approach step count — 4 or 5. The bowler knows their own pattern, so this is authoritative: the analyzer reports it as the step count and cross-checks it against auto-detection (a mismatch flags low phase-detection confidence). Stored on Session.meta.approach_step_count and forwarded to aikmodels. Silently ignored for non-bowling activities. Omit to auto-detect.

  • 4 - 4-step
  • 5 - 5-step
integer
Allowed values: 4 5
barbell_mass_kg

Barbell mass in kg for weightlifting sessions — total load on the bar including the bar itself. The lifter declares it at upload (it is not derivable from video: the plate detector tracks bar position, not load). Feeds the GRF / power formulas (F = (m_athlete + m_barbell) × (a + g)). Stored on Session.meta.barbell_mass_kg and forwarded to aikmodels. Silently ignored for non-weightlifting activities. Omit when unknown — mass-dependent lift metrics are then suppressed rather than computed from an assumed load.

number format: double
>= 1 <= 500
walk_test_distance_m

Measured course length in metres for a fixed-distance walk test — the 10 m walk, or the 6 m / 4 m gait-speed variants. The distance is a property of the protocol (marked on the floor, measured with a tape), so it cannot be recovered from the video: declare it here and the analyzer reports walking speed as distance ÷ traversal time, bypassing the height-derived pixel scale the standard speed estimate depends on. Stored on Session.meta.walk_test_distance_m and forwarded to aikmodels. Silently ignored for non-walking activities. Omit for a free walk with no marked course.

number format: double
>= 2 <= 100
Examples
ExampleRunning,WithReservedSessionIdFromUpload-intent

Running, with reserved session_id from upload-intent

{
  "id": "5c836d7d-3301-49df-bfa0-9cff0550fd0e",
  "activity": "running",
  "exercise": "Treadmill",
  "video_url": "https://s3.ai.aikynetix.app/aikynetix-media/teams/2648a781-8751-47c0-836d-2c0189792d71/sessions/2026/04/5c836d7d-3301-49df-bfa0-9cff0550fd0e.source.mp4",
  "client": "f6d52e64-3aa3-4a26-bac2-0fc9d718448d",
  "camera_view": "side"
}

Responses

Section titled “Responses”

201

Section titled “201”
Media typeapplication/json
object
id
required

Server-assigned UUID. Use the same value as session_id from the upload-intent step to keep the storage object key consistent.

string format: uuid
activity
required

Activity family — running, walking, jumps, weightlifting, agility, mobility, fencing, ergonomics. Drives which analyzer runs.

  • running - Running
  • walking - Walking
  • jump - Vertical Jump
  • weightlifting - Weightlifting
  • mobility - Mobility Assessment
  • workspace_wellness - Workspace Wellness
  • agility - Agility
  • fencing - Fencing
  • cycling - Cycling
  • tennis - Tennis
  • padel - Padel Tennis
  • bowling - Bowling
  • baseball - Baseball
  • football - Football
  • badminton - Badminton
  • cricket - Cricket
  • basketball - Basketball
  • scuba_diving - Scuba Diving
  • ice_hockey - Ice Hockey
  • american_football - American Football
  • fri - Falls Risk Indicator
string
Allowed values: running walking jump weightlifting mobility workspace_wellness agility fencing cycling tennis padel bowling baseball football badminton cricket basketball scuba_diving ice_hockey american_football fri
exercise

Specific movement within the activity (e.g. Treadmill, Back Squat, Single-Leg Stand). Pick from GET /api/exercises/?activity=....

string
<= 80 characters
name
required
string
seq_no
required

Stable per-team session number (#941), assigned at create time and immutable — the shared reference coaches use to point at a video (‘look at session 42’). Monotonic per team in creation order; survives filter / sort / pagination and reads the same for every teammate. Gaps appear where sessions were deleted (numbers are never reused). null on demo sessions (cross-team, deliberately unnumbered) and on the public /api/shared/{token}/ payload, where the team-internal ordinal is withheld from anonymous viewers.

integer
nullable
status
required

Lifecycle state: pending (queued) → processing (analyzer running) → completed (metrics + annotated mp4 ready) | failed (see failure_reason).

  • pending - Pending
  • processing - Processing
  • completed - Completed
  • failed - Failed
string
Allowed values: pending processing completed failed
video_url
Any of:
string format: uri
<= 1000 characters
analyzed_url
required

Public URL of the annotated playback mp4 — pose skeleton drawn over the original frames. Populated when status == 'completed'; empty before that and during reanalyze.

string format: uri
anonymized_url
required

Public URL of a face-anonymised copy of the source video WITHOUT the pose overlay (#1233) — the privacy-safe ‘raw’ source for the player’s overlay toggle. Populated only on Face-Blur sessions (blur_face == true); empty otherwise, when the best-effort clean render failed, and during reanalyze. On non-blur sessions the player toggles to video_url directly. On the public /api/shared/{token}/ payload the un-anonymised video_url is withheld for blur sessions and this field is the only ‘raw’ source.

string format: uri
pose3d_url
required

Public URL of the 3D pose sidecar JSON (#1356) — the per-frame 3D joint track uploaded next to the annotated mp4, consumed by the player’s interactive 3D viewer. Empty when the 3D lifter isn’t configured on the inference service, when its best-effort generation failed, and during reanalyze — clients then hide the 3D view. Served on the public /api/shared/{token}/ payload, EXCEPT on a Face-Blur session: it carries no imagery, but it reconstructs the athlete’s movement in full, so it is blanked there alongside video_url.

string format: uri
thumbnail_url
required

Public URL of a static JPG poster (~5-15 KB) extracted at ~0.5 s of the annotated mp4. The SPA renders this on the journal row instead of mounting a <video preload=metadata> per row, which avoids the main-thread freeze on long session lists. Empty when aikmodels couldn’t generate one — clients fall back to analyzed_url and decode the first frame themselves.

string format: uri
fps

Frame rate the session was ANALYSED at — read off the normalized file, not the upload. Every metric and per-frame derivative in the report is a function of this number, which is why it is the one reported. It is min(AIKMODELS_NORMALIZE_FPS, source_fps) (#1951), so on a 60 or 120 fps upload it reads BELOW what the coach filmed; compare source_fps to tell the two apart.

integer
nullable <= 32767
source_fps

Frame rate the camera actually captured at, probed before our normalize resample. Null on older sessions and when the probe could not run. Present so a client can say “filmed at 60, analysed at 30” rather than showing our rate as though it were the coach’s (#1951). May be fractional — 23.976 and 29.97 are real capture rates.

number format: double
nullable
duration_ms

Source video duration in milliseconds.

integer
nullable <= 2147483647
processed_at
required

ISO-8601 UTC timestamp of the session’s LAST successful analysis. Null until the first one completes; it is NOT cleared afterwards, so a session that delivered a report once and was then re-analyzed keeps its timestamp while sitting on pending/processing/failed.

string format: date-time
nullable
created_at
required

ISO-8601 UTC timestamp of session creation.

string format: date-time
client
required

UUID of the Client (athlete) the session is about. Optional but strongly recommended — without a client, body-aware metric adjustments fall back to defaults.

string format: uuid
nullable
uploaded_by
required

UUID of the Admin who uploaded the session. Team-scoped listings carry it so per-coach surfaces (e.g. the upload wizard’s recent-combos row) can filter to the current admin’s own history without leaking a teammate’s picks. null for legacy rows created before attribution was recorded.

string format: uuid
nullable
failure_reason
required

Human-readable explanation when status == 'failed'. Empty otherwise.

string
metrics
required

List of all SessionMetric rows attached to this session — joint angles, timings, scores, the full per-key catalogue the analyzer emitted. Empty until status == 'completed'.

Array<object>
object
key
string
value_num
number
nullable
value_json
object
metric_targets
required

Body-aware-adjusted green-zone bounds keyed by metric: {key: {min_good, max_good, amber_low, amber_high, higher_is_better, beta}}. Already accounts for the athlete’s gender + height — front-end can render the zone directly without re-applying any adjustment. amber_low / amber_high are the ONROM (amber) outer bounds of the three-tier clinical band (#521); both null ⇒ classic binary green zone (the front-end derives the wnl/onrom/high_risk tier from them). beta flags a metric that has not cleared clinical validation (UI shows a precision caveat). Empty list when the activity has no zone-defining specs.

object
key
additional properties
camera_view
required

side / front / back. Read-only; derived from the value passed at session create time. Lets the player UI badge the view and hide metric cards that don’t apply.

string
capture_findings
required

Capture-quality findings for a COMPLETED session (#1868) — the typed defect taxonomy evaluated from the inference service’s capture signals: [{code, severity, data}], e.g. {"code": "pose_sparse", "severity": "advisory", "data": {"detection_ratio": 0.42}}. Empty list = evaluated clean; null = the session predates capture evaluation (never conflate the two). Codes: pose_sparse / implausible_geometry / subject_too_far / camera_off_plane / subject_left_frame. Severity is advisory-only today — fatal capture problems FAIL the session and speak through failure_reason.

Array<object>
nullable
object
key
additional properties
handedness
required

right / left dominant hand or foot, or null. Read-only; from the value passed at create time. Seeds the reprocess dialog so a handedness-aware re-run keeps the athlete’s side instead of silently defaulting to right-handed (#775).

string
nullable
is_demo
required
boolean
progress
required

Worker’s most recent stage emit while this session is in flight. null for terminal states, queued sessions, and any read failure — the SPA renders a queued placeholder in those cases. Polled via the existing session-detail refetch (every 2 s while pending/processing); no separate endpoint.

object
stage
required

Pipeline stage the worker is currently executing (e.g. download, pose_extract, draw). The full stage list is hardcoded on each side and kept in sync via a contract test (apps/api side) — adding or renaming a stage is a cross-track PR per ADR-0011.

string
stage_idx
required

0-based index of stage in the worker’s stage order.

integer
frame_done
required

Frames processed so far inside the current stage. Only moves during stages with sub-progress (today: pose_extract); 0 elsewhere.

integer
frame_total
required

Total frame count for the current stage; 0 when the stage has no frame counter or the worker hasn’t computed it yet.

integer
has_active_share
required

Whether a live public share link exists for this session — so the player can offer Revoke on a session shared in an earlier visit. null means NOT REPORTED, which is every list response: the value is annotated by the session-detail view only, because a per-row lookup would be one query per session on a list that has no use for it. Treat null as ‘unknown’, not as ‘no share’.

boolean
nullable
locale
required

Language (en / ru / es) frozen on the share when the coach created/refreshed it — only populated on the public GET /api/shared/{token}/ response, where the /r/<token> page reads it to render its whole UI in the same language as the AI coaching paragraph (issue #339). null on the authenticated session endpoints, which follow the coach’s own UI locale.

string
nullable
blur_face
required

True when this session was created with the Blur Face option — the analysed video has the subject’s face anonymised. Read-only; false for every session created without the flag.

boolean
barbell_mass_kg
required

The lifter’s declared total bar load in kg, or null when never declared. Read-only; from the value passed at create time (#1325). Seeds the reprocess dialog so a weightlifting re-run keeps the declared load instead of silently losing it (the repoint clears stale meta by default).

number format: double
nullable
walk_test_distance_m
required

The declared walk-test course in metres, or null when the session has none (#1493). Read-only. Seeds the reprocess dialog so a Timed Walk re-run keeps the measured course — and so a course typed wrong at upload can be corrected there instead of re-filming a perfectly good walk.

number format: double
nullable
has_scuba_meta
required

True when this session already has a scuba session-meta sidecar on Session.meta.scuba. A boolean only — the clinical payload (side / condition / arms-engaged) is never exposed. The reprocess dialog gates on it: a scuba re-run that already has a sidecar carries the stored one over (no blind overwrite); one without it (legacy / re-routing in from another activity) must supply it (#775).

boolean
report_count
required

How many active Solution reports bind this session — the reverse of the report→sessions link, shown as a ‘used in N reports’ badge on the journal row (#1192). Only populated on the session-list endpoint (the view seeds a per-page map to avoid N+1); null everywhere else, where the FE simply omits the badge.

integer
nullable
reports
required

The active Solution reports that bind this session, each with a ready name + slug — powers the ‘used in N reports’ links on the single-session player (#1192). Only populated on the session-detail endpoint (the view seeds the reverse-scan for the one session); an empty list elsewhere, where the FE shows no links.

Array<object>
object
id
required
string
name
required
string
solution_slug
required
string
movement_guide
required

Movement Norms Library entry for this session’s movement (reference table + explanation), localised to the session’s locale. Populated ONLY on the public shared payload (#1118) so the /r/ report renders the guide without a second authenticated call; null on the authenticated app (which calls GET /api/movement-guide/) and when the library has no entry.

object
activity
required
string
exercise
required
string
what_it_measures
required

Plain-English description of the movement and what its variables capture.

string
key_fact
required

One evidence-backed fact, with citation where available.

string
demographics
required

How the bands shift by sex/age.

string
skill
required

What improves from beginner to advanced.

string
metrics
required

Per-metric reference row for the Movement Guide table. min_good/max_good are the team-default reference band (same as the Threshold configurator) in the metric’s canonical unit; evidence_basis is validated | experimental | assumed; reference_only metrics are library variables we don’t yet compute for a session.

Array<object>
object
key
required
string
label
required
string
unit
required
string
higher_is_better
required
boolean
nullable
min_good
required
number format: double
nullable
max_good
required
number format: double
nullable
evidence_basis
required
string
source
required
string
note
required
string
per_athlete
required
boolean
reference_only
required
boolean
Examples
ExampleCreated,QueuedForAnalysis

Created, queued for analysis

{
  "id": "5c836d7d-3301-49df-bfa0-9cff0550fd0e",
  "activity": "running",
  "exercise": "Treadmill",
  "status": "pending",
  "video_url": "https://s3.ai.aikynetix.app/aikynetix-media/teams/2648a781-8751-47c0-836d-2c0189792d71/sessions/2026/04/5c836d7d-3301-49df-bfa0-9cff0550fd0e.source.mp4",
  "analyzed_url": "",
  "thumbnail_url": "",
  "fps": null,
  "duration_ms": null,
  "processed_at": null,
  "created_at": "2026-04-29T11:15:55Z",
  "client": "f6d52e64-3aa3-4a26-bac2-0fc9d718448d",
  "uploaded_by": "9b3f1c2a-7e44-4d1b-8c0a-12ab34cd56ef",
  "failure_reason": "",
  "metrics": [],
  "metric_targets": {},
  "camera_view": "side"
}

400

Section titled “400”
Media typeapplication/json
object
detail
required

Human-readable message, or a stable machine code for the cases a client branches on. The standard envelope for 400 (validation — a field-keyed object may appear instead), 401 (missing / invalid credentials), 403 (authenticated but not permitted), and 404 (absent — cross-team records are collapsed to 404 so the API never leaks the existence of another team’s data).

string
Examplegenerated
{
  "detail": "example"
}

401

Section titled “401”
Media typeapplication/json
object
detail
required

Human-readable message, or a stable machine code for the cases a client branches on. The standard envelope for 400 (validation — a field-keyed object may appear instead), 401 (missing / invalid credentials), 403 (authenticated but not permitted), and 404 (absent — cross-team records are collapsed to 404 so the API never leaks the existence of another team’s data).

string
Examplegenerated
{
  "detail": "example"
}

402

Section titled “402”
Media typeapplication/json
object
detail
required

One of five canonical strings. The front-end paywall switches copy + CTA on this value (exact string equality — do not localise). quota_exhausted / seat_limit_reached / client_limit_reached / feature_not_in_plan lead to an upgrade CTA; subscription_suspended leads to a Billing Portal CTA so the buyer can update their payment method.

  • quota_exhausted - Session quota for the period reached 0
  • subscription_suspended - Stripe dunning in flight (past_due / unpaid)
  • seat_limit_reached - Adding another team member would exceed plan.max_seats
  • client_limit_reached - Adding another Client would exceed plan.max_client_profiles
  • feature_not_in_plan - The tier does not include this whole feature surface
string
Allowed values: quota_exhausted subscription_suspended seat_limit_reached client_limit_reached feature_not_in_plan
reset_at
required

ISO-8601 UTC timestamp the team’s current period ends. Null when the team has no live subscription (legacy un-migrated row). On Free + paid this is the renewal moment; quota refreshes to exactly plan.session_quota (NOT additive — leftover sessions don’t roll over).

string format: date-time
nullable
current_plan
required

The active plan’s role string (free, starter, professional, organization, strategic). Same value as current_role — kept as two separate fields for forward-compatibility with a future named-plan split where current_plan could carry an SKU and current_role the tier label.

string
current_role
required

The active plan’s role string. See current_plan.

string
feature

Which feature surface is locked. Present ONLY on feature_not_in_plan, so one modal can name what’s gated without a detail string per feature (#773). The only value today is agents (aikynetix/agents/services.py::AGENTS_FEATURE).

string
Examples

Free team uploaded 5 sessions this period, hit the 6th

{
  "detail": "quota_exhausted",
  "reset_at": "2026-06-01T00:00:00Z",
  "current_plan": "free",
  "current_role": "free"
}

403

Section titled “403”
Media typeapplication/json
object
detail
required

Human-readable message, or a stable machine code for the cases a client branches on. The standard envelope for 400 (validation — a field-keyed object may appear instead), 401 (missing / invalid credentials), 403 (authenticated but not permitted), and 404 (absent — cross-team records are collapsed to 404 so the API never leaks the existence of another team’s data).

string
Examplegenerated
{
  "detail": "example"
}

503

Section titled “503”
Media typeapplication/json
object
detail
required

503 — a downstream dependency was unavailable and the request could not be served (e.g. enqueue_failed when the analysis queue can’t accept the job). Safe to retry with backoff.

string
Examples
Example503—CouldNotQueueAnalysis

Quota debited then the task broker was unreachable; retry

{
  "detail": "enqueue_failed"
}