VOD Timestamps API

Authentication

{
  "email": "you@example.com",
  "password": "your-password"
}

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

curl -X POST https://koalavod.com/api/auth/api-token \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your-password"
  }'

Endpoint

Request

Send a Twitch VOD ID or a supported VOD URL in `vod_id`.

{
  "vod_id": "2299099099"
}

Response

The response includes VOD metadata, credit info, structured timestamp groups divided like the gallery copy export, and a `copy_text` field that matches the gallery export format. Timestamp detection uses the same standard default analysis pipeline as a fresh `/app` load, not user-specific saved settings.

{
  "success": true,
  "vod_id": "2299099099",
  "metadata": {
    "title": "Example stream title",
    "user_name": "example_streamer",
    "created_at": "2026-03-01T12:34:56Z",
    "platform": "twitch"
  },
  "credits": {
    "charged": true,
    "remaining": 2
  },
  "timestamps": [
    {
      "key": "likely",
      "title": "Likely interesting moments (I)",
      "timestamps": [
        {
          "start_seconds": 1234,
          "end_seconds": 1264,
          "start_hms": "00:20:34",
          "end_hms": "00:21:04",
          "range_hms": "00:20:34 - 00:21:04"
        }
      ]
    }
  ],
  "copy_text": "Hype moments from ..."
}

Credit rules

• The first successful request for a VOD this month costs 1 VOD credit.
• Requesting the same VOD again in the same month is free.
• Emails in `ADMIN_EMAILS` do not consume VOD credits.
• `credits.bypassed` is only included when an admin bypass was actually applied.
• If you have no credits left and the VOD has not been counted this month, the API returns `429`.

Browser example

const tokenResponse = await fetch("/api/auth/api-token", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: "you@example.com",
    password: "your-password",
  }),
});

const { token } = await tokenResponse.json();

const response = await fetch("/api/vod-timestamps", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${token}`,
  },
  body: JSON.stringify({
    vod_id: "2299099099",
  }),
});

const data = await response.json();
console.log(data);

curl -X POST https://koalavod.com/api/vod-timestamps \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "vod_id": "2299099099"
  }'

Errors

• `401` when the bearer token is missing or invalid.
• `500` from `/api/auth/api-token` if server auth config is unavailable.
• `403` from `/api/auth/api-token` when email verification is required.
• `423` from `/api/auth/api-token` when the account is temporarily locked.
• `400` for invalid or missing `vod_id`.
• `404` when the VOD or comments cannot be loaded.
• `429` when no VOD credits remain for a new VOD this month.