Partner API — kontinuum

Getting started

Authentication

All requests require your API key as a Bearer token in the Authorization header. Keys are issued per partner and are environment-specific — sandbox keys route to the same endpoints but are flagged as sandbox traffic.

Authorization: Bearer kont_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Your API key is available in the partner portal. Never expose it client-side.

Status

Check connectivity and confirm your key is valid before sending events.

GET /api/v1/status

Response

{
  "status":         "ok",
  "partner":        "JamBay",
  "partner_status": "sandbox",
  "event_model":    "batch",
  "api_version":    "v1"
}

partner_status reflects your account tier: demo, sandbox, or active.

Responses

All event write endpoints return 202Accepted on success — not 200. This signals that the event has been received and durably stored, even if title matching or downstream enrichment hasn't completed yet. Your integration should treat 202 as success.

HTTP/2 202
Content-Type: application/json

{ "status": "accepted" }

Idempotency

Every event endpoint accepts an optional event_id field. When provided, Kontinuum guarantees that the same (partner_id, event_id) pair is only stored once — duplicate submissions are silently ignored and still return 202.

Recommended: Use a stable, unique ID per event (e.g. a UUID generated at event time). This makes retries and batch replays safe without any coordination on your end.

{
  "event_id": "evt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "partner_user_id": "u_8821",
  ...
}

event_id is scoped to your partner account — there's no collision risk with other partners' IDs.

Events

Common fields

These fields appear on every event endpoint.

Field	Type		Description
event_id	string	optional	Unique ID for idempotent delivery
partner_user_id	string	required	Your internal user ID — opaque to Kontinuum
partner_title_id	string	required	Your internal title ID
partner_title_name	string	required	Title as displayed in your UI
partner_title_slug	string	required	URL slug, e.g. `the-shawshank-redemption`
release_year	integer	required	Year title was first released
content_type	enum	required	`movie` · `tv` · `sport`
event_timestamp	string	required	ISO 8601 with timezone, e.g. `2026-07-28T20:00:00Z`
season_number	integer	tv only	Season number
episode_number	integer	tv only	Episode number within season
episode_title	string	optional	Episode title — aids matching

Watch event

POST /api/v1/events/watch Record a user watching a title

Additional fields

Field	Type		Description
position_seconds	integer	optional	Playback position at time of event
completed	boolean	optional	True if the user finished the title. Default: `false`
partner_app_id	string	optional	Alternate title ID for deep links (e.g. Amazon ASIN)

Example — movie

curl -X POST https://kontinuum.one/api/v1/events/watch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id":           "evt_abc123",
    "partner_user_id":    "u_8821",
    "partner_title_id":   "tt0111161",
    "partner_title_name": "The Shawshank Redemption",
    "partner_title_slug": "the-shawshank-redemption",
    "release_year":       1994,
    "content_type":       "movie",
    "position_seconds":   5400,
    "completed":          true,
    "event_timestamp":    "2026-07-28T20:00:00Z"
  }'

Example — TV episode

curl -X POST https://kontinuum.one/api/v1/events/watch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id":           "evt_def456",
    "partner_user_id":    "u_8821",
    "partner_title_id":   "tt0944947",
    "partner_title_name": "Game of Thrones",
    "partner_title_slug": "game-of-thrones",
    "release_year":       2011,
    "content_type":       "tv",
    "season_number":      1,
    "episode_number":     1,
    "episode_title":      "Winter Is Coming",
    "position_seconds":   3200,
    "completed":          true,
    "event_timestamp":    "2026-07-28T21:00:00Z"
  }'

Response

HTTP/2 202
{ "status": "accepted" }

Favorite event

POST /api/v1/events/favorite User adds or removes a favorite

Additional fields

Field	Type		Description
action	enum	required	`added` · `removed`

Example

curl -X POST https://kontinuum.one/api/v1/events/favorite \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id":           "evt_ghi789",
    "partner_user_id":    "u_8821",
    "partner_title_id":   "tt0111161",
    "partner_title_name": "The Shawshank Redemption",
    "partner_title_slug": "the-shawshank-redemption",
    "release_year":       1994,
    "content_type":       "movie",
    "action":             "added",
    "event_timestamp":    "2026-07-28T20:05:00Z"
  }'

Rating event

POST /api/v1/events/rating User rates a title

Additional fields

Field	Type		Description
rating	string	required	See rating values below

Rating values

Value	Normalized
`thumbs_up` · `like` · `positive`	8.0 / 10
`thumbs_down` · `dislike` · `negative`	3.0 / 10
Any decimal string, e.g. `"8.5"`	Stored as-is

List event

POST /api/v1/events/list User adds or removes from a named list

Additional fields

Field	Type		Description
list_name	string	required	Name of the list, e.g. `watchlist`
action	enum	required	`added` · `removed`

Batch events

POST /api/v1/events/batch Submit up to 500 events in one request

Mixed event types are allowed in a single batch. Events are processed independently — a failure on one does not block others. Use event_id on each event for safe replays.

Request body

{
  "events": [
    {
      "event_id":           "evt_001",
      "event_type":         "watch",
      "partner_user_id":    "u_8821",
      "partner_title_id":   "tt0111161",
      "partner_title_name": "The Shawshank Redemption",
      "partner_title_slug": "the-shawshank-redemption",
      "release_year":       1994,
      "content_type":       "movie",
      "position_seconds":   5400,
      "completed":          true,
      "event_timestamp":    "2026-07-28T20:00:00Z"
    },
    {
      "event_id":           "evt_002",
      "event_type":         "favorite",
      "partner_user_id":    "u_8821",
      "partner_title_id":   "tt0111161",
      "partner_title_name": "The Shawshank Redemption",
      "partner_title_slug": "the-shawshank-redemption",
      "release_year":       1994,
      "content_type":       "movie",
      "action":             "added",
      "event_timestamp":    "2026-07-28T20:05:00Z"
    }
  ]
}

event_type values

watch · favorite · rating · list

Response

HTTP/2 202
{
  "status":   "accepted",
  "accepted": 2,
  "failed":   0
}

If any events fail, the response includes an errors array with per-event details. Batches exceeding 500 events return 413.

Query

Watch state

GET /api/v1/watch-state/{partner_user_id}

Returns the current watch state for a user — their most recent position and completion status per title, aggregated across all linked platforms.

Response

{
  "partner_user_id": "u_8821",
  "titles": [
    {
      "partner_title_id": "tt0111161",
      "title":            "The Shawshank Redemption",
      "position_seconds": 5400,
      "completed":        true,
      "last_watched":     "2026-07-28T20:00:00",
      "source_partner":   "jambay"
    }
  ]
}

source_partner is the slug of the partner that recorded the most recent event for that title. Returns an empty titles array if the user has no linked Kontinuum account.

Favorites

GET /api/v1/favorites/{partner_user_id}

Returns titles currently in the user's favorites, net of add and remove events.

Response

{
  "partner_user_id": "u_8821",
  "titles": [
    {
      "partner_title_id": "tt0111161",
      "title":            "The Shawshank Redemption",
      "added_at":         "2026-07-28T20:05:00"
    }
  ]
}

Profile

GET /api/v1/profile/{partner_user_id}

Returns the full Kontinuum profile for a user: watch state, favorites, and sports follows across all linked platforms.

Response

{
  "partner_user_id":        "u_8821",
  "kontinuum_profile_id":   "uuid",
  "verified":               true,
  "watch_state":            [ ... ],
  "favorites":              [ ... ],
  "sports_follows":         [
    {
      "entity_type":    "team",
      "entity_id":      "123",
      "follow_source":  "jambay",
      "followed_at":    "2026-07-01T12:00:00"
    }
  ]
}

Returns {"partner_user_id": "...", "verified": false} if the user has no linked account.

Verify user

POST /api/v1/partners/verify-user

Check whether a partner user ID is linked to a Kontinuum profile, without fetching full profile data.

Request body

{ "partner_user_id": "u_8821" }

Response

{ "verified": true, "kontinuum_profile_id": "uuid" }

Verify link

POST /api/v1/partners/verify-link

Complete the account linking flow. Users receive a short verification code from Kontinuum; your app submits it here to confirm the link.

Request body

{
  "partner_user_id":   "u_8821",
  "verification_code": "A3K9"
}

Response

{ "verified": true }

Returns {"verified": false, "error": "Invalid or expired code"} if the code is wrong or has expired.

Reference

Error codes

Code	Meaning
401	Missing or invalid API key
413	Batch exceeds 500 events — split into smaller batches
422	Validation error — check required fields and types

Notes

All timestamps must be ISO 8601 with timezone, e.g. 2026-07-28T20:00:00Z
partner_title_name and partner_title_slug should reflect your platform's own spelling — not TMDb's canonical title
Events are never dropped — unmatched titles are queued for editorial review and resolved asynchronously
Once a title alias is resolved, all future events with that partner_title_id resolve instantly
Partner user IDs are opaque strings — Kontinuum never stores PII
Query endpoints return cross-platform data for users who have linked their account; unlinked users return empty or verified: false

API Reference

Authentication

Status

Response

Responses

Idempotency

Common fields

Watch event

Additional fields

Example — movie

Example — TV episode

Response

Favorite event

Additional fields

Example

Rating event

Additional fields

Rating values

List event

Additional fields

Batch events

Request body

event_type values

Response

Watch state

Response

Favorites

Response

Profile

Response

Verify user

Request body

Response

Verify link

Request body

Response

Error codes

Notes