API

Analysing a broadcast from your own code

Upload the file to the bucket, call one endpoint with the path, and KAIROS runs the same analysis the app runs. Your workspace, your plan, your allowance — an API key does nothing a signed-in person could not do.

The whole thing, end to end

Five calls. Uploading and analysing are separate on purpose: you can push a batch of files overnight and decide later which of them to analyse.

# 1. Ask for somewhere to put the file.
curl -sX POST https://kairosapp.tech/api/uploads \
  -H "Authorization: Bearer $KAIROS_KEY" \
  -H 'content-type: application/json' \
  -d '{"filename":"match.mp4","sizeBytes":734003200}'
# -> {"path":"tenants/…/inbox/Ab3…/match.mp4","sessionUri":"https://storage.googleapis.com/…"}

# 2. Send the bytes. One PUT if it is small; see "Sending the bytes" for chunks.
curl -sX PUT "$SESSION_URI" --upload-file match.mp4

# 3. Start the analysis, naming the path from step 1.
curl -sX POST https://kairosapp.tech/api/analyses \
  -H "Authorization: Bearer $KAIROS_KEY" \
  -H 'content-type: application/json' \
  -d '{"path":"tenants/…/inbox/Ab3…/match.mp4","title":"France v Spain","domain":"sport"}'
# -> {"assetId":"e5f1…","status":"uploaded"}

# 4. Wait for it.
curl -s https://kairosapp.tech/api/assets/e5f1…/progress -H "Authorization: Bearer $KAIROS_KEY"
# -> {"phase":"analysing","heartbeatAgeSeconds":4,…}   then eventually {"phase":"done",…}

# 5. Read it.
curl -s https://kairosapp.tech/api/assets/e5f1…/timeline -H "Authorization: Bearer $KAIROS_KEY"

Authentication

Every call carries Authorization: Bearer kai_sk_…. Create a key under Settings; it is shown once and cannot be shown again, so put it straight into wherever you keep secrets. Revoking is on the same screen, and takes effect on the next call.

Sending the bytes

POST /api/uploads gives you a sessionUri. The bytes go to Google Cloud Storage directly — not through KAIROS — so a broadcast-sized file is not passing through anybody’s API. Small files can go in one PUT. Anything large should be chunked, so a dropped connection costs one chunk rather than the whole upload.

PUT <sessionUri>
Content-Range: bytes 0-16777215/734003200      # 16 MiB, a multiple of 256 KiB

308 Resume Incomplete
Range: bytes=0-16777215                        # what GCS ACTUALLY kept — resume from here

PUT <sessionUri>
Content-Range: bytes 16777216-33554431/734003200
...
200 OK                                         # the last chunk answers 200 or 201

Lost track after a crash? Ask, do not guess:

PUT <sessionUri>
Content-Range: bytes */734003200               # no body: "how much do you have?"

308 Resume Incomplete
Range: bytes=0-50331647                        # continue from 50331648

A session lasts a week. After that, ask for a new one — the old path is dead and nothing was created, so there is nothing to clean up.

The endpoints

Following a run

progress returns a phase. Poll it about every 10 seconds — that is what the app’s own screen does — and stop when the phase is one of the terminal ones. heartbeatAgeSeconds is how long since the machine doing the work last checked in; it is only set while something is actually running, and a number climbing past a minute or two is the signal that a run is in trouble rather than merely slow.

There is no percentage and no estimate, because there is no honest one to give: the analyser is a single opaque run that reports nothing from inside itself, and the measured read rate varies by nearly three times across broadcasts. The phases are what is actually known.

Being called back

Rather than polling to the end, register a callback under Settings and KAIROS will POST to it when an analysis settles. One callback per workspace, https only. You are given a signing secret once, at that moment.

POST https://your-service.example.com/kairos
X-Kairos-Timestamp: 1786291200
X-Kairos-Signature: sha256=3f1c…

{
  "event": "analysis.settled",
  "assetId": "e5f1…",
  "status": "complete",
  "domain": "sport",
  "durationSeconds": 5412.32,
  "timelineUrl": "https://kairosapp.tech/api/assets/e5f1…/timeline",
  "occurredAt": "2026-08-20T14:31:07.221Z"
}

It carries a link to the timeline rather than the timeline itself — a two-hour broadcast is hundreds of segments, and you read them with your own key, so nothing decides on your behalf what you may see.

Verifying it

The signature is an HMAC-SHA256 over <timestamp>.<raw body>. Check the timestamp before you trust the digest: that is what makes a captured delivery useless to replay later.

import { createHmac, timingSafeEqual } from 'node:crypto';

// The RAW body. Parsing it to JSON and re-serialising changes bytes, and the signature is over bytes.
export function verify(rawBody, headers, secret) {
  const timestamp = headers['x-kairos-timestamp'];
  const signature = (headers['x-kairos-signature'] || '').replace(/^sha256=/, '');
  if (!timestamp || !signature) return false;

  // Refuse an old delivery even when its signature is perfect — that is what stops a replay.
  const age = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
  if (!Number.isFinite(age) || age > 300) return false;

  const expected = Buffer.from(createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex'));
  const offered = Buffer.from(signature);
  // Constant time, and the length check first: timingSafeEqual throws on a mismatch rather than failing.
  return expected.length === offered.length && timingSafeEqual(expected, offered);
}

Limits

• Your plan’s caps apply exactly as they do in the app: file size, bytes per month, minutes, and whether the sport pipeline is available at all. A refusal names the reason code, and the codes are in the tables above.
• domain cannot be changed after the analysis starts. It selects the pipeline, and the run is paid for either way.
• One analysis per uploaded object. Naming the same path twice answers 409 rather than analysing it again — upload the file again if you genuinely want a second run.
• Deleting a broadcast does not give its minutes back. Uploading, analysing and deleting in a loop is not a way around an allowance.
• An object you upload and never analyse stays in the bucket, and counts toward your bytes for the month until you analyse it or it is removed. Nothing removes it for you, so a script that uploads more than it analyses is eventually refused.
• A callback whose address stops resolving publicly is refused at delivery time rather than silently dropped, and the attempt is recorded either way. Repointing the hostname at an internal address after registering it does not work.