Mobile & TV App REST API
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.

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 ————-|
- 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}
- 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.”}
- 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:
- Base URL: https://yourdomain.com/wp-json/movie-engine/v1/app
- Required Headers:
- X-ME-App-Key: [YOUR_API_KEY]
- X-ME-Platform: [android|ios|android_tv|apple_tv]
- Authorization: Bearer [ACCESS_TOKEN] (when logged in)
Key Features to Implement:
- Bootstrap: Fetch GET /config for primary theme color, site name, and minimum version.
- Home Screen: Call GET /home and dynamically render Hero Sliders, Continue Watching rows, and Category Carousels using the sections array.
- 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.
- 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.
- In-App Promo Codes: Provide a “Redeem Voucher” screen calling POST /coupon/redeem for instant free VIP activation.
- 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.
