Documentation

Quick start

1. Create an account at /register. You get 100 free points.
2. Open API keys and create a key. Copy it right away: it is shown only once.
3. Make a request:

curl https://api.example.com/v1/movie/550 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "success": true,
  "data": {
    "id": 550,
    "name": "Fight Club",
    "type": "movie",
    "url": "https://stream.example.com/movie/550.m3u8",
    "headers": {
      "Origin": "https://example.com",
      "Referer": "https://example.com/"
    }
  },
  "usage": {
    "cost": 5,
    "remaining_points": 95
  }
}

Authentication

Send your key in the Authorization header as a Bearer token. Keys start with kine_live_.

Authorization: Bearer kine_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys are not accepted in the URL, because URLs end up in logs. Keep keys on your server. If a key leaks, revoke it on the API keys page; it stops working immediately.

Costs

Points are reserved before upstream playback sources are resolved. If the title does not exist or the upstream source provider fails, points are refunded automatically and the response shows your balance. Each successful response includes usage.cost and usage.remaining_points.

Movie Playback Source

id is a positive whole number (the TMDB movie ID).

curl https://api.example.com/v1/movie/27205 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "success": true,
  "data": {
    "id": 27205,
    "name": "Inception",
    "type": "movie",
    "url": "https://stream.example.com/movie/27205.m3u8",
    "headers": {
      "Origin": "https://example.com",
      "Referer": "https://example.com/"
    }
  },
  "usage": { "cost": 5, "remaining_points": 95 }
}

TV Playback Source

Request playback for a specific episode by passing season and episode in the URL.

curl https://api.example.com/v1/tv/1399/2/5 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "success": true,
  "data": {
    "id": 1399,
    "name": "Game of Thrones",
    "type": "tv",
    "season": 2,
    "episode": 5,
    "url": "https://stream.example.com/tv/1399.m3u8",
    "headers": {
      "Origin": "https://example.com",
      "Referer": "https://example.com/"
    }
  },
  "usage": { "cost": 5, "remaining_points": 95 }
}

Premium Titles

Premium status is determined automatically by the server based on the requested TMDB ID. Callers use the normal movie and TV endpoints:

• If the requested ID is normal: charged 5 points.
• If the requested ID is premium: charged 10 points.

Discover Premium Titles

Returns the catalog of currently active premium titles:

{
  "success": true,
  "data": [
    { "id": 550, "name": "Fight Club", "type": "movie" },
    { "id": 1399, "name": "Game of Thrones", "type": "tv" }
  ]
}

Search History

curl -X POST https://api.example.com/v1/search/history \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "inception"}'

Nothing is saved if the user turned search history off in Settings. The response then says "saved": false.

Watch history

Call it as playback progresses. One row is kept per movie or episode, and later calls update it. Progress of 90% or more (when duration is sent) marks the title as watched.

curl -X POST https://api.example.com/v1/watch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"video_id": 1399, "video_type": "tv", "video_name": "Game of Thrones",
       "season": 1, "episode": 2, "progress": 600, "duration": 3000}'

Account balance

{
  "success": true,
  "data": {
    "points_balance": 95,
    "costs": { "normal": 5, "premium": 10 },
    "key": { "name": "My app", "prefix": "kine_live_ab12", "scopes": ["movie:read"] }
  }
}

Other public endpoints

Errors

Errors always look like this:

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_POINTS",
    "message": "Not enough points for this request",
    "required": 5,
    "remaining": 2
  }
}

Rate limits

Each key can make 60 requests per minute. Every response carries:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1767225600   (unix time when the window resets)

When you go over, you get 429 with a Retry-After header. Requests rejected by the rate limiter never cost points.

Scopes

Give each app a key with only the scopes it needs.

Payment webhooks

Payment providers notify the server at POST /v1/webhooks/payments. The request is accepted only if its signature is valid, so this endpoint is not for client use. Points are added only after the provider confirms the payment, never because the browser says so. Delivering the same event twice adds points once.