A presigned PUT for one clip

POST

/api/portal/{client_id}/uploads/intent/

const url = 'http://localhost:8000/api/portal/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/uploads/intent/';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"content_type":"video/mp4","size_bytes":48211337,"filename":"run.mp4"}'
};

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/portal/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/uploads/intent/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "content_type": "video/mp4", "size_bytes": 48211337, "filename": "run.mp4" }'

Upload the clip to url with method and headers, then send session_id to POST …/uploads/ within 45 minutes (the PUT is signed for 30, plus a margin). The PUT must carry exactly size_bytes bytes: the size is signed. 400 for a content type that is not video/* or application/octet-stream, or clip_too_large (max_bytes) past the upload limit. 409 upload_cap_reached when this month’s cap is used up — an intent not yet sent holds its slot until it lapses (checked again at the create); 429 upload_attempts_exceeded past 10 intents a day; 403 access_ended team_plan while the team cannot run analyses.

The Contribute level only: a View grant gets 403 contribute_required.

The signed-in person’s grant on the card in the path. Every route answers 404 while client access is switched off on the environment. 404 card_not_found for a card the account never held — another athlete’s, a card of the account’s own team, or an id that names nothing. 403 access_ended (reason: revoked · team_plan · minor) for a card it held and can no longer open, consent_required when the consent texts changed since the person accepted them (consent again with POST /api/portal/{client_id}/consent/). A partner API key gets 403. 429 past the account’s rate (client_portal, 120/min; the PDFs client_portal_pdf, 20/min).

Only what a coach released is visible, curated on the server: the team’s hidden metrics are absent, the coach’s AI text and internal fields are not sent, and media URLs are signed for two hours.

Authorizations

Parameters

Path Parameters

client_id

required

string format: uuid

Request Body^required

object

content_type

required

MIME type of the clip; replayed as the PUT Content-Type. video/* or application/octet-stream only, as the coach’s upload intent (#1735): anything else is 400.

string

>= 1 characters <= 120 characters

size_bytes

required

The clip’s size in bytes (File.size). Checked against the upload limit, then signed into the PUT: storage refuses a body of any other length.

integer

>= 1

filename

Never used as the storage key.

string

>= 1 characters <= 200 characters

Examples

AClip

A clip

{
  "content_type": "video/mp4",
  "size_bytes": 48211337,
  "filename": "run.mp4"
}

object

content_type

required

MIME type of the clip; replayed as the PUT Content-Type. video/* or application/octet-stream only, as the coach’s upload intent (#1735): anything else is 400.

string

>= 1 characters <= 120 characters

size_bytes

required

The clip’s size in bytes (File.size). Checked against the upload limit, then signed into the PUT: storage refuses a body of any other length.

integer

>= 1

filename

Never used as the storage key.

string

>= 1 characters <= 200 characters

Example ^generated

content_type=example&size_bytes=1&filename=example

object

content_type

required

MIME type of the clip; replayed as the PUT Content-Type. video/* or application/octet-stream only, as the coach’s upload intent (#1735): anything else is 400.

string

>= 1 characters <= 120 characters

size_bytes

required

The clip’s size in bytes (File.size). Checked against the upload limit, then signed into the PUT: storage refuses a body of any other length.

integer

>= 1

filename

Never used as the storage key.

string

>= 1 characters <= 200 characters

Responses

200

application/json

PortalUploadIntent: a presigned PUT for one clip.

object

session_id

required

The upload id; send it back to create.

string format: uuid

url

required

string

method

required

string

headers

required

object

key

additional properties

string

public_url

required

string

Examples

Intent

{
  "session_id": "7c1e2d3f-4a5b-4c6d-8e7f-90a1b2c3d4e5",
  "url": "https://s3.example.com/aikynetix-media/teams/t/sessions/2026/11/u.source.mp4?X-Amz-Signature=…",
  "method": "PUT",
  "headers": {
    "Content-Type": "video/mp4"
  },
  "public_url": "https://s3.example.com/aikynetix-media/teams/t/sessions/2026/11/u.source.mp4"
}

400

A stable code (clip_too_large), or errors keyed by field.

application/json

Any of:

object
object

A stable code in detail (and code), with its limit.

object

detail

required

string

code

string

max_bytes

integer

Validation errors keyed by field — each key an offending field of the body, each value its human-readable messages (or a stable code, e.g. not_editable).

object

key

additional properties

Array<string>

Examples

400 — too large

{
  "detail": "clip_too_large",
  "code": "clip_too_large",
  "max_bytes": 524288000
}

400 — not a video

{
  "content_type": [
    "Unsupported video content type 'text/html'. Expected a `video/*` MIME type (or `application/octet-stream`)."
  ]
}

401

application/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

Example ^generated

{
  "detail": "example"
}

403

application/json

object

detail

required

access_ended, consent_required, or DRF’s message for a partner API key.

string

reason

With access_ended: why the card no longer opens — revoked, team_plan or minor.

string

client_name

string

team_name

string

consent_version

With consent_required: the version to accept.

string

kinds

With consent_required: the texts to show.

Array<string>

Examples

403 — access ended

{
  "detail": "access_ended",
  "reason": "team_plan",
  "client_name": "Sofia Lebedeva",
  "team_name": "North Track Academy"
}

403 — a View grant

{
  "detail": "contribute_required"
}

404

application/json

object

detail

required

string

Example ^generated

{
  "detail": "example"
}

409

application/json

object

detail

required

409 — the request conflicts with current state. detail is a stable code (e.g. reanalyze_in_flight, already_on_plan, email_in_use). Some 409s carry extra context fields alongside detail; those are documented on the specific endpoint that emits them.

string

Examples

409—CapReached

409 — cap reached

{
  "detail": "upload_cap_reached"
}

429

application/json

object

detail

required

429 — throttled: this account’s (or address’s) rate for the route is used up; try again after wait seconds, which Retry-After repeats. A route with a limit of its own answers its own code instead, documented there.

string

wait

With throttled: whole seconds until the next request can pass.

integer

nullable

Examples

429—TooManyAttemptsToday

429 — too many attempts today

{
  "detail": "upload_attempts_exceeded"
}

A presigned PUT for one clip

Authorizations

Parameters

Path Parameters

Request Bodyrequired

Examples

Example generated

Responses

200

Examples

400

Examples

401

Example generated

403

Examples

404

Example generated

409

Examples

429

Examples

Request Body^required

Example ^generated

Example ^generated

Example ^generated