AiKYNETIX Support
Overview
AiKYNETIX API 1.0.0
Section titled “AiKYNETIX API 1.0.0”AI motion-analysis for sports coaches, athletes and clinics. Upload a short video of an athlete; get back joint angles, ground-contact times, peak forces, a technique score, and an annotated playback video — same API the AiKYNETIX web app runs on.
Quick start
POST /api/sessions/upload-intent/ → { session_id, url, headers, public_url }
PUT <url> (raw video bytes, MP4 / MOV / WebM, ≤200 MB)
POST /api/sessions/ → { id, status: "pending" } (debits 1 quota)
GET /api/sessions/<id>/ (poll ~1 Hz until status == "completed")
GET /api/sessions/<id>/coaching/ (SSE — AI written analysis, optional)All write endpoints accept JSON. Lists are paginated as
{ results, count, next, previous } (default limit=50, max 200).
Authentication
Three schemes. Partner and user credentials go in Authorization: Bearer <token> — the server routes any aik_-prefixed token to the
partner-key authenticator and falls through to Firebase JWT otherwise.
The first-party web app’s server tier additionally authenticates with a
Firebase session cookie under its own Session prefix (not Bearer).
| Scheme | Header | Use case |
|---|---|---|
ApiKeyBearer |
Authorization: Bearer aik_… |
Server-to-server partner integrations. Minted by the team owner on the Organization plan or above via POST /api/api-keys/ (plaintext shown once). Scoped to the issuing team and that team’s quota. Rotate by minting a new one + revoking the old. |
FirebaseBearer |
Authorization: Bearer <firebase-id-token> |
Short-lived (1 h) Firebase ID token from the web/mobile SDK. Refresh with getIdToken(true). First request from an unknown UID auto-provisions an Admin + personal Team. |
FirebaseSessionCookie |
Authorization: Session <firebase-session-cookie> |
First-party only: the web app’s Next.js server forwards its httpOnly Firebase session cookie when rendering on a signed-in user’s behalf. Browsers never send this credential, and it is not available to partner integrations. |
The partner API key reaches the team-scoped read/write endpoints under
the Sessions, Clients, Catalogue, and Billing (read-only) tags.
API Keys, Account, Team, Dashboard, and Thresholds are
human-admin-only and require the Firebase scheme.
Errors
Every error response carries { "detail": "<machine-code-or-message>" }.
Endpoint-specific 402 / 409 / 410 payloads carry extra fields documented
on the operation. Reference shapes live in components/schemas as
ErrorDetailResponse, PaywallErrorResponse, ConflictResponse,
ServiceUnavailableResponse, and RateLimitResponse.
| Code | Component | When |
|---|---|---|
400 |
ErrorDetailResponse |
Validation failure or typed detail code (invalid_code, unknown_price, …). |
401 |
ErrorDetailResponse |
Missing / invalid / expired bearer token. |
402 |
PaywallErrorResponse |
One of quota_exhausted / subscription_suspended / seat_limit_reached / client_limit_reached / feature_not_in_plan; carries reset_at (ISO-8601 or null) + current_plan + current_role, plus feature on the feature gate. |
403 |
ErrorDetailResponse |
Authenticated but the role / plan gate refused (e.g. owner-only, Organization-and-above only). |
404 |
ErrorDetailResponse |
Absent — or hidden cross-team (we collapse 403 → 404 so the API never confirms the existence of another team’s data). |
409 |
ConflictResponse |
Resource-state collision (already_on_plan, reanalyze_in_flight, email_in_use, …). Some 409s carry endpoint-specific context fields beyond detail. |
410 |
ErrorDetailResponse |
Resource was valid but is now gone — expired share token, expired verification code. |
429 |
RateLimitResponse |
Currently emitted only by POST /api/me/verify-email/ as too_many_attempts after 5 wrong codes (per-code attempt cap, not a request-rate limit). The rest of the API is not throttled in v1; broader throttling is a v1.6 follow-up. |
503 |
ServiceUnavailableResponse |
A downstream dependency was unavailable (e.g. enqueue_failed when the analysis queue is unreachable). Safe to retry with backoff. |
Pagination
List endpoints under Sessions, Clients, and the Thresholds
audit feeds use DRF’s standard limit/offset envelope:
GET /api/sessions/?limit=50&offset=0
→ { "count": 173, "next": "…?limit=50&offset=50", "previous": null, "results": [ … ] }limit defaults to 50 and is capped at 200. The Dashboard, Catalogue,
and the threshold navigation endpoints return a single aggregated
object rather than a paginated page — those carry no envelope. The
API Keys list is unpaginated: it returns the team’s keys as a plain
array with no envelope and ignores ?limit=.
Versioning
Single version 1.0.0. Breaking changes ship under a new major version
prefix; additive changes (new optional fields, new operations, looser
validation) ship under the same version. Subscribe to the changelog at
https://ai.aikynetix.app/changelog for deprecation notices — anything
slated for removal will be marked deprecated: true on its operation at
least one release ahead of the cut.
Endpoints below are grouped by tag; click into a tag for its behaviours, examples and full schema.
Support: support@aikynetix.com
Authentication
Section titled “Authentication”ApiKeyBearer
Section titled “ApiKeyBearer”Long-lived partner API key for server-to-server calls. Mint one via POST /api/api-keys/ while signed in with a Firebase token; the plaintext key is shown ONCE in the creation response and only its bcrypt hash is stored. The key is scoped to the active Team at creation time and shares that team’s session quota. Rotate by minting a new key and revoking the old one (DELETE /api/api-keys/<id>/).
Security scheme type: http
Bearer format: AiKYNETIX API key (aik_…)
FirebaseBearer
Section titled “FirebaseBearer”Short-lived (1 hour) Firebase ID token minted client-side via the Firebase Auth SDK after sign-in. Refresh with getIdToken(/* forceRefresh = */ true). Server validates every request through firebase_admin.auth.verify_id_token. First request from a new Firebase user auto-provisions an Admin record + their personal Team.
Security scheme type: http
Bearer format: Firebase ID Token
FirebaseSessionCookie
Section titled “FirebaseSessionCookie”Server-to-server scheme for the first-party Next.js SSR tier. Format: Authorization: Session <firebase-session-cookie> — note the Session prefix, not Bearer. The app server forwards its httpOnly Firebase session cookie; browsers never send this credential directly, and it is not available to partner integrations. Validated via firebase_admin.auth.verify_session_cookie.
Security scheme type: apiKey
Header parameter name: Authorization
localJwtAuth
Section titled “localJwtAuth”Locally-issued JWT for deployments running local auth (no Firebase). Obtain via POST /api/auth/login/; send as Authorization: Bearer <token>.
Security scheme type: http
Bearer format: JWT