Skip to content
Developer Guide

Mobile & TV App REST API

Estimated reading: 12 minutes 22 views

Available in the newer MovieEngine Pro build (Version 7, as shown in development). Not present in version 1.0.8.

Target audience: Frontend mobile developers (Flutter, React Native, Swift, Kotlin), Smart TV developers (Android TV, Apple TV, Fire TV), and AI prompts / documentation generators.
Plugin: Cine Movie Engine Pro (cine-movie-engine-pro)

1. System Overview & Architecture

MovieEngine Pro provides a secure, high-performance REST API designed specifically for native mobile and connected TV applications. It directly interfaces with the WordPress database (wp_users, wp_posts, wp_postmeta, and taxonomies) while enforcing cryptographic stream authorization, paywall restrictions, and real-time user library synchronization.

Key Capabilities

  • Direct Database Sync: WordPress user authentication, registrations, watchlists, playback progress, and content ratings.
  • Smart TV 6-Digit Pairing: Seamless TV activation without on-screen password typing.
  • In-App Purchases (IAP): Native integration for Google Play Billing (Android) and Apple StoreKit 2 (iOS).
  • VIP Voucher / Promo Code Engine: Direct in-app redemption for instant membership activation.
  • Cryptographic Stream Protection: HMAC-SHA256 signed streaming links (me_app_sig) compatible with ExoPlayer, AVPlayer, and VLC while blocking web hotlinking.
  • Catalog & Cast Directory: Full taxonomy support (Genres, Years, Countries, Qualities) plus actor/director filmographies.

2. Base Configuration & Global Headers

Base Endpoint

https://yourdomain.com/wp-json/movie-engine/v1/app

Global Required Headers

Every API request MUST include the following HTTP headers:

  • X-ME-App-Key (String) — Secret API key configured in MovieEngine > API Settings. Example: me_app_**********adsfdf
  • X-ME-Platform (String) — Client platform identifier (android, ios, android_tv, apple_tv). Example: android
  • Content-Type (String) — Required for all POST requests. Example: application/json

The example key above is a placeholder format only. Use a real key generated per site, keep it secret, and rotate it if it is ever exposed.

User Authentication Header

For endpoints requiring a logged-in user:

Authorization: Bearer <access_token>

Admin Settings Page (MovieEngine > Mobile & TV App REST API)

The screenshot below shows the settings page in the newer build (local dev site movieengine.local, status ACTIVE). This is where the API is enabled and configured — no code changes needed.

Mobile & TV App REST API settings page — Enable toggle on, masked App Secret API Key, all four platforms enabled, token expiry 30 days, minimum app version 1.0.0, Home Screen Builder, and the endpoint list

What the screenshot shows:

  • Enable Mobile & TV App REST API — ON. Connects native Android, iOS (iPhone/iPad), Android TV, and Apple TV apps directly to the WordPress database (users, login, registration, movies, series, watch history, watchlist, memberships).
  • App Secret API Key (Header: X-ME-App-Key) — Masked value with Copy Key and Regenerate Key buttons. Pass this key in the X-ME-App-Key header from mobile and TV apps. Click Save Changes after regenerating. (The key in the screenshot is masked — never share an unmasked key.)
  • Allowed App Platforms (Header: X-ME-Platform) — All four enabled: Android App (android), iOS / iPadOS (ios), Android TV (android_tv), Apple TV (apple_tv).
  • Auth Token Expiry (Days): 30. Minimum Required App Version: 1.0.0. Store Update URL (Optional): Play Store URL field.
  • Enable App Maintenance Mode — OFF in the screenshot.
  • App Home Screen Builder & Layout — Which content rows appear on home screens, with custom titles and item limits. Enabled in the screenshot: Featured Hero Slider (6 items), Continue Watching Row, Trending Now Row (12), Latest Movies Row (12), TV Series Row (12). Disabled: Top Rated Row (12) and Genre Carousels (top popular genres, 8 movies each).
  • In-App Purchases (Google Play & Apple App Store) — Users buy VIP/Pro subscriptions inside native apps via Google Play Billing & Apple StoreKit. Store SKUs are set per plan under MovieEngine > Membership Plans (“Google Play Product ID” and “Apple Store Product ID”). Purchases are verified & logged via POST /membership/purchase.
  • App REST Base URL & Endpoints — Base URL shown: http://movieengine.local/wp-json/movie-engine/v1/app (local dev URL — replace with the production domain). The endpoint grid lists: GET /config, POST /auth/login, POST /auth/register, POST /auth/tv-code/request, POST /auth/tv-code/verify, GET /home, GET /catalog, GET /movie/{id}, GET /series/{id}, GET /episode/{id}, GET /person/{id}, GET /taxonomies, GET /plans, POST /membership/purchase, POST /coupon/validate, POST /coupon/redeem, POST /request, GET|POST /user/watchlist, GET|POST /user/progress.

Note: the screenshot’s endpoint grid does not show /user/like, /user/rate, or /user/profile, which are listed in section 3.12 of this document. Confirm whether those three exist in this build before relying on them.

3. Endpoints Specification

3.1 App Bootstrap & Configuration

  • Route: GET /config
  • Access: Public (App Key only)
  • Description: Called when the app launches to retrieve branding, player preferences, app version requirements, maintenance mode status, and genres.

Response 200 OK:

{
“success”: true,
“site”: {
“name”: “MovieEngine”,
“description”: “Watch HD Movies & TV Series”,
“url”: “https://yourdomain.com/“,
“primary_color”: “#E50914”
},
“app”: {
“min_version”: “1.0.0”,
“update_url”: “https://play.google.com/store/apps/…”,
“maintenance_mode”: false,
“maintenance_msg”: “”,
“platforms”: {
“android”: true,
“ios”: true,
“android_tv”: true,
“apple_tv”: true
}
},
“player”: {
“skip_intro”: true,
“auto_next_episode”: true,
“next_episode_timer”: 10,
“resume_playback”: true
},
“genres”: [
{ “id”: 12, “name”: “Action”, “slug”: “action”, “count”: 140 },
{ “id”: 15, “name”: “Sci-Fi”, “slug”: “sci-fi”, “count”: 85 },
{ “id”: 18, “name”: “Drama”, “slug”: “drama”, “count”: 120 }
]
}

3.2 Authentication & User Registration

A. User Login

  • Route: POST /auth/login
  • Access: Public (App Key only)

Request Body:

{
“username”: “[email protected]“,
“password”: “your_secure_password”
}

Response 200 OK:

{
“success”: true,
“access_token”: “eyJhbGciOiJIUzI1NiIsIn…”,
“token_type”: “Bearer”,
“user”: {
“id”: 24,
“username”: “johndoe”,
“email”: “[email protected]“,
“display_name”: “John Doe”,
“avatar”: “https://secure.gravatar.com/avatar/…”,
“is_vip”: true,
“active_plan_id”: 88,
“active_plan”: “VIP Monthly”,
“registered_date”: “2026-01-15 10:20:00”
}
}

B. User Registration

  • Route: POST /auth/register
  • Access: Public (App Key only)

Request Body:

{
“email”: “[email protected]“,
“password”: “securepassword123”,
“name”: “Alex Mercer”,
“username”: “alex”
}

Response 201 Created:

{
“success”: true,
“access_token”: “eyJhbGciOiJIUzI1NiIsIn…”,
“token_type”: “Bearer”,
“user”: {
“id”: 25,
“username”: “alex”,
“email”: “[email protected]“,
“display_name”: “Alex Mercer”,
“avatar”: “https://secure.gravatar.com/avatar/…”,
“is_vip”: false,
“active_plan”: “Free”,
“registered_date”: “2026-11-10 14:00:00”
}
}

3.3 Smart TV 6-Digit Code Pairing Flow

Eliminates the friction of typing passwords on TV remotes:

[Smart TV App] [Mobile/Web App]
| |
|– 1. POST /auth/tv-code/request ————>|
|<– Returns 6-digit Code (e.g. 849201) ——–|
| (Displays on TV screen) |
| |
| |– 2. User enters 849201
| | POST /auth/tv-code/verify
| | (Approved by logged-in user)
| |
|– 3. POST /auth/tv-code/poll —————>|
|<– Receives Bearer Access Token ————-|

  1. Step 1 — TV Requests 6-Digit Code:
    • POST /auth/tv-code/request
    • Payload: {“device_name”: “Living Room Android TV”}
    • Returns: {“success”: true, “code”: “849201”, “device_token”: “a1b2…”, “expires_in”: 600}
  2. Step 2 — Mobile User Approves Code:
    • POST /auth/tv-code/verify (Header: Authorization: Bearer <token>)
    • Payload: {“code”: “849201”}
    • Returns: {“success”: true, “message”: “TV approved successfully.”}
  3. Step 3 — TV Polls for Authorization:
    • POST /auth/tv-code/poll
    • Payload: {“code”: “849201”, “device_token”: “a1b2…”}
    • Returns: {“success”: true, “access_token”: “…”, “user”: {…}} (when approved).

3.4 Home Feed (Dashboard Layout)

  • Route: GET /home
  • Access: App Key (+ Optional Bearer Token for personalized watch progress)
  • Description: Delivers ready-made rows and carousels for the application home screen.

Response 200 OK:

{
“success”: true,
“sections”: [
{
“id”: “featured”,
“title”: “Featured Spotlight”,
“type”: “hero_slider”,
“items”: [
{
“id”: 120,
“type”: “movie”,
“title”: “Inception”,
“poster”: “https://yourdomain.com/wp-content/uploads/poster.jpg“,
“backdrop”: “https://yourdomain.com/wp-content/uploads/backdrop.jpg“,
“rating”: 8.8,
“release_year”: “2010”,
“runtime”: “148 min”,
“genres”: [“Action”, “Sci-Fi”],
“is_premium”: false
}
]
},
{
“id”: “continue_watching”,
“title”: “Continue Watching”,
“type”: “continue_watching_row”,
“items”: [
{
“id”: 120,
“type”: “movie”,
“title”: “Inception”,
“poster”: “https://…”,
“resume_position”: 1420.5,
“duration_sec”: 8880.0
}
]
},
{ “id”: “trending”, “title”: “Trending Now”, “type”: “carousel”, “items”: […] },
{ “id”: “latest_movies”, “title”: “Latest Movies”, “type”: “carousel”, “items”: […] },
{ “id”: “latest_series”, “title”: “TV Series”, “type”: “carousel”, “items”: […] },
{ “id”: “top_rated”, “title”: “Top Rated”, “type”: “carousel”, “items”: […] }
]
}

3.5 Catalog Search & Filters

  • Route: GET /catalog
  • Access: App Key (+ Optional Bearer Token)

Query Parameters:

  • type: all | movie | series
  • search / q: Keyword search term
  • genre: Taxonomy ID or Slug (e.g. action, drama)
  • year: Release year (e.g. 2025, 2024)
  • country: Country taxonomy slug or ID (e.g. usa, korea)
  • quality: Video resolution (e.g. 4K UHD, 1080p)
  • language: Audio language
  • director: Director name/term
  • cast: Actor name/term
  • sort: latest | popular | rating | title
  • page: Page index (Default 1)
  • per_page: Items per page (Default 20, Max 50)

3.6 Content Details & Native Playback

A. Movie Details

  • Route: GET /movie/{id}
  • Response Highlights:
    • Full synopsis, tagline, content rating, likes, views.
    • Cast members with character roles & headshot photos.
    • Directing & production credits.
    • HMAC signed stream URLs with timestamp expiry for native ExoPlayer / AVPlayer.
    • Subtitle tracks with WebVTT endpoints.

Example stream URL:

https://yourdomain.com/wp-json/movie-engine/v1/stream/120?index=0&me_exp=…&me_app_sig=…

B. TV Series Details

  • Route: GET /series/{id}
  • Response Highlights: Complete nested tree of all Seasons (seasons[]) and Episodes (episodes[]) with episode titles, thumbnails, and numbers.

C. Episode Details

  • Route: GET /episode/{id}
  • Response Highlights: Stream URLs, intro skip points (intro_start, intro_end), recap skip points (recap_start, recap_end), and next/previous episode IDs.

3.7 Cast & Crew (Person Profile & Filmography)

  • Route: GET /person/{id}
  • Access: Public (App Key only)

Response 200 OK:

{
“success”: true,
“person”: {
“id”: 45,
“name”: “Leonardo DiCaprio”,
“photo”: “https://yourdomain.com/wp-content/uploads/person.jpg“,
“biography”: “Leonardo DiCaprio is an American actor…”,
“birthday”: “1974-11-11”,
“deathday”: “”,
“place_of_birth”: “Los Angeles, California, USA”,
“known_for”: “Acting”,
“gender”: “Male”,
“social_links”: {
“twitter”: “https://twitter.com/LeoDiCaprio“,
“instagram”: “https://instagram.com/leonardodicaprio“
},
“acting_credits”: [
{
“id”: 120,
“type”: “movie”,
“title”: “Inception”,
“release_year”: “2010”,
“poster”: “https://…”
}
],
“directing”: []
}
}

3.8 Taxonomies Directory

  • Route: GET /taxonomies
  • Access: Public (App Key only)
  • Description: Returns arrays of { id, name, slug, count } for all genres, release years, video qualities, countries, languages, studios, and networks.

3.9 In-App Purchases (Google Play & Apple Store)

A. Retrieve Membership Plans & Store SKUs

  • Route: GET /plans

{
“success”: true,
“plans”: [
{
“id”: 88,
“name”: “Pro Monthly VIP”,
“price”: 9.99,
“formatted_price”: “$9.99”,
“currency”: “USD”,
“interval”: “month”,
“device_limit”: 4,
“features”: [“Ultra HD 4K”, “No Advertisements”, “Downloads Allowed”],
“is_hot”: true,
“badge”: “Popular”,
“google_product_id”: “cme_pro_monthly”,
“apple_product_id”: “cme_pro_monthly_ios”
}
]
}

B. Verify & Activate In-App Purchase

  • Route: POST /membership/purchase
  • Access: Authenticated (Authorization: Bearer <token>)

Request Body:

{
“plan_id”: 88,
“platform”: “android”,
“product_id”: “cme_pro_monthly”,
“purchase_token”: “google_play_purchase_token_here”,
“order_id”: “GPA.3321-4432-5541-12345”
}

Response 200 OK:

{
“success”: true,
“message”: “Subscription verified and activated successfully.”,
“plan_id”: 88,
“plan_name”: “Pro Monthly VIP”,
“expiry”: “December 10, 2026”,
“expiry_timestamp”: 1796918400,
“membership”: {
“is_premium”: true,
“type”: “premium”,
“plan_name”: “Pro Monthly VIP”
}
}

3.10 Coupons & VIP Promo Code Vouchers

A. Validate Promo Code

  • Route: POST /coupon/validate
  • Request: {“code”: “SUMMERVIP”}
  • Response:

{
“success”: true,
“valid”: true,
“code”: “SUMMERVIP”,
“is_vip_access”: true,
“vip_duration_days”: 30
}

B. Redeem Promo Voucher (Direct In-App Activation)

  • Route: POST /coupon/redeem
  • Access: Authenticated (Authorization: Bearer <token>)
  • Request: {“code”: “SUMMERVIP”}

Response 200 OK:

{
“success”: true,
“message”: “Success! VIP access granted for 30 days.”,
“duration_days”: 30,
“expiry_formatted”: “December 10, 2026”,
“expiry_timestamp”: 1796918400,
“membership”: {
“is_premium”: true,
“plan_name”: “VIP Access”
}
}

3.11 Content Request from App

  • Route: POST /request
  • Access: Authenticated (Authorization: Bearer <token>)

Request Body:

{
“title”: “Spider-Man: Beyond the Spider-Verse”,
“type”: “movie”,
“year”: “2026”,
“language”: “English”,
“message”: “Please upload in 4K UHD with English subtitles.”
}

3.12 User Library, Watch History & Interactions

(All require Authorization: Bearer <token>)

  • Get Watchlist — GET /user/watchlist — Returns list of saved movie/series cards
  • Toggle Watchlist — POST /user/watchlist — {“post_id”: 120} (Adds or removes item)
  • Get Watch History — GET /user/progress — Returns items with previous playback seconds
  • Save Live Progress — POST /user/progress — {“post_id”: 120, “seconds”: 1420.5, “duration”: 8880.0}
  • Toggle Like — POST /user/like — {“post_id”: 120} (Likes or unlikes content)
  • Submit Rating — POST /user/rate — {“post_id”: 120, “rating”: 9.5} (1 to 10 scale)
  • Get Profile — GET /user/profile — User info, avatar, VIP status & plan expiry

4. Prompt Template for AI Assistants (Muse AI / Cursor / Claude)

Copy and paste the prompt below directly into your AI assistant:

You are building a cross-platform mobile and TV application (iOS, Android, Android TV, Apple TV) using the MovieEngine Pro REST API backend.

Backend Specs:

Key Features to Implement:

  1. Bootstrap: Fetch GET /config for primary theme color, site name, and minimum version.
  2. Home Screen: Call GET /home and dynamically render Hero Sliders, Continue Watching rows, and Category Carousels using the sections array.
  3. Player: In ExoPlayer/AVPlayer, pass the signed stream_url from GET /movie/{id} or GET /episode/{id}. Every 10 seconds, send playback progress to POST /user/progress.
  4. Monetization: Call GET /plans to display subscription options with Google Play SKU (google_product_id) and Apple SKU (apple_product_id). When user completes purchase in store, send receipt to POST /membership/purchase.
  5. In-App Promo Codes: Provide a “Redeem Voucher” screen calling POST /coupon/redeem for instant free VIP activation.
  6. Smart TV 6-Digit Pairing: On TV apps, call POST /auth/tv-code/request to show code, then poll POST /auth/tv-code/poll until user approves on phone.

Refer to the complete endpoints and schemas documented in MOBILE_APP_REST_API.md.

5. Notes for Implementers

  • Base URL is a placeholder. Replace yourdomain.com with the real site domain. All example titles, IDs, tokens, and prices are example data.
  • Auth model: Every request needs X-ME-App-Key + X-ME-Platform. Logged-in actions additionally need Authorization: Bearer <access_token>.
  • Playback progress: Send progress to POST /user/progress regularly during playback (e.g. every 10 seconds) so Continue Watching and resume work across devices.
  • Stream security: Stream URLs are HMAC-SHA256 signed with a timestamp expiry — do not cache or share them, and always fetch a fresh URL before playback.
  • TV pairing expiry: Pairing codes expire after 600 seconds (10 minutes). If a code expires, request a new one.
Share this Doc

Mobile & TV App REST API

Or copy link

CONTENTS
Back To Top