Add a period video to a bout
const url = 'http://localhost:8000/api/bouts/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/periods/';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"video_url":"https://media.example.com/teams/9b1c7e2a/sessions/2026/10/0c5b1d7e-6a2f-4e3b-8d19-5f0a7c2e4b61.mp4","lamps":[[0.44,0.49,0.47,0.52],[0.51,0.49,0.54,0.52]],"strip":[[[0.33,0.66],[0.35,0.58]],[[0.5,0.66],[0.5,0.58]],[[0.67,0.66],[0.65,0.58]]]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url http://localhost:8000/api/bouts/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/periods/ \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "video_url": "https://media.example.com/teams/9b1c7e2a/sessions/2026/10/0c5b1d7e-6a2f-4e3b-8d19-5f0a7c2e4b61.mp4", "lamps": [ [ 0.44, 0.49, 0.47, 0.52 ], [ 0.51, 0.49, 0.54, 0.52 ] ], "strip": [ [ [ 0.33, 0.66 ], [ 0.35, 0.58 ] ], [ [ 0.5, 0.66 ], [ 0.5, 0.58 ] ], [ [ 0.67, 0.66 ], [ 0.65, 0.58 ] ] ] }'Attaches one uploaded video — one period of the bout — with the scoring-lamp boxes and the three strip lines the coach marked on one frame. With lamps, a background read proposes the touches (detect_status goes pending → running → done / failed); without them detect_status is skipped and the coach marks the touches with PUT /touches/. Costs nothing. Refused (400) past a bout’s period limit, for a video stated longer than a period is read, and while the team already has the most period reads queued; 402 for a read-only team.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Request Bodyrequired
Section titled “Request Bodyrequired”object
public_url from POST /api/sessions/upload-intent/ — one period of the bout.
Seconds into the video of the frame the lamps and the strip were marked on. The camera pans and zooms; the marks are carried from this frame. Omitted = the first frame. Within the first 60 s.
Scoring-lamp boxes [x0, y0, x1, y1], normalised to the frame. Omit when the lamps are out of frame: the coach then marks the touches.
Three lines across the strip — both en-garde lines and the centre line — each as two frame points, edge to edge. Their order does not matter.
Examples
A period with lamps and the strip
{ "video_url": "https://media.example.com/teams/9b1c7e2a/sessions/2026/10/0c5b1d7e-6a2f-4e3b-8d19-5f0a7c2e4b61.mp4", "lamps": [ [ 0.44, 0.49, 0.47, 0.52 ], [ 0.51, 0.49, 0.54, 0.52 ] ], "strip": [ [ [ 0.33, 0.66 ], [ 0.35, 0.58 ] ], [ [ 0.5, 0.66 ], [ 0.5, 0.58 ] ], [ [ 0.67, 0.66 ], [ 0.65, 0.58 ] ] ]}object
public_url from POST /api/sessions/upload-intent/ — one period of the bout.
Seconds into the video of the frame the lamps and the strip were marked on. The camera pans and zooms; the marks are carried from this frame. Omitted = the first frame. Within the first 60 s.
Scoring-lamp boxes [x0, y0, x1, y1], normalised to the frame. Omit when the lamps are out of frame: the coach then marks the touches.
Three lines across the strip — both en-garde lines and the centre line — each as two frame points, edge to edge. Their order does not matter.
Example generated
video_url=example&duration_s=1&marked_s=1&lamps=%5B1%5D&strip=%5B%5B1%5D%5Dobject
public_url from POST /api/sessions/upload-intent/ — one period of the bout.
Seconds into the video of the frame the lamps and the strip were marked on. The camera pans and zooms; the marks are carried from this frame. Omitted = the first frame. Within the first 60 s.
Scoring-lamp boxes [x0, y0, x1, y1], normalised to the frame. Omit when the lamps are out of frame: the coach then marks the touches.
Three lines across the strip — both en-garde lines and the centre line — each as two frame points, edge to edge. Their order does not matter.
Responses
Section titled “Responses”object
Examples
The period, its lamps queued for reading
{ "id": "a3e1c9f0-52b7-4d16-8c0e-91f4b2d7e6a5", "index": 0, "video_url": "https://media.example.com/teams/9b1c7e2a/sessions/2026/10/0c5b1d7e-6a2f-4e3b-8d19-5f0a7c2e4b61.mp4", "duration_s": null, "calibration": { "lamps": [ [ 0.44, 0.49, 0.47, 0.52 ], [ 0.51, 0.49, 0.54, 0.52 ] ] }, "detect_status": "pending", "detect_error": ""}object
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).
Example generated
{ "detail": "example"}object
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).
Example generated
{ "detail": "example"}object
One of eight 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; exercise_not_in_plan leads to a contact-us CTA — the movement list is sales-managed, no tier adds to it (#2030). trial_expired / access_ended mean the team is read-only (#2901): everything opens, nothing new is created; they lead to a subscribe CTA and always carry reset_at: null.
quota_exhausted- Session quota for the period reached 0subscription_suspended- Stripe dunning in flight (past_due / unpaid)seat_limit_reached- Adding another team member would exceed plan.max_seatsclient_limit_reached- Adding another Client would exceed plan.max_client_profilesfeature_not_in_plan- The tier does not include this whole feature surfaceexercise_not_in_plan- The (activity, exercise) is not in the team’s exercise grantstrial_expired- The team is read-only: its self-serve trial endedaccess_ended- The team is read-only: its paid plan or granted access ended
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).
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.
The active plan’s role string. See current_plan.
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).
Example
{ "detail": "quota_exhausted"}object
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).
Example generated
{ "detail": "example"}object
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).
Example generated
{ "detail": "example"}