API Documentation

Developer
Documentation

Integrate our powerful movie recommendation API into your applications with ease. Get started in minutes with our comprehensive guides and examples.

Get Started Quick Start

Screenpick API
Documentation

Integrate AI-powered movie recommendations into your applications with our simple and powerful API.

Documentation

Endpoints

Introduction

Welcome to the Screenpick API – your gateway to intelligent, AI-powered movie discovery. Our sophisticated recommendation engine leverages advanced machine learning algorithms to understand natural language queries and deliver personalized movie suggestions that match your exact preferences, mood, or specific criteria.

What Makes Screenpick Special

•Natural Language Processing: Describe what you want in plain English – no complex filters needed
•Contextual Understanding: Our AI grasps nuanced requests like "uplifting movies for rainy days" or "mind-bending sci-fi without horror elements"
•Rich Movie Data: Get comprehensive movie information from The Movie Database (TMDb) including ratings, release dates, and plot summaries
•Cross-Database Integration: Seamlessly retrieve both TMDb and IMDb identifiers for external integrations

Perfect For Developers

Integrate intelligent movie recommendations into your apps, websites, or services. Our RESTful API is designed for easy integration with comprehensive documentation and code examples.

Enterprise Ready

Built with scalability and reliability in mind, featuring rate limiting, comprehensive error handling, and multiple authentication options to meet enterprise requirements.

API Architecture

The Screenpick API follows RESTful principles and returns responses in JSON format. All endpoints support CORS for browser-based applications and require HTTPS for secure communication. Our API is built on a modern, scalable infrastructure ensuring fast response times and high availability.

Base URL

https://screenpick.fun/api/

💡 Pro Tip

Start with our health check endpoint (/api/ping) to verify connectivity, then explore our AI recommendations endpoint with simple queries like "popular comedies" or "award-winning dramas from the 2010s" to see the power of our natural language processing.

Authentication

The Screenpick API supports both JWT-based authentication and traditional API key authentication. We recommend using JWT tokens for enhanced security, session management, and better integration with modern applications. All API requests require valid authentication.

🔑 New: JWT Authentication

We now support JWT (JSON Web Token) authentication for enhanced security and better session management. JWT tokens provide stateless authentication with automatic expiration and refresh capabilities.

Getting Started

Get your API key from RapidAPI
Exchange API key for JWT tokens via /api/auth/login
Use JWT tokens for API requests
Refresh tokens when needed via /api/auth/refresh

Authentication Methods

JWT Bearer Token: Modern, secure (recommended)
API Key Header: Traditional method
X-RapidAPI-Key: RapidAPI integration
Query Parameter: For testing only

JWT Authentication Flow

Step 1: Login with API Key

Exchange your API key for JWT tokens by calling the login endpoint:

POST /api/auth/login

{
  "apiKey": "your_api_key_here"
}

Step 2: Use JWT Token

Include the JWT token in your API requests:

Authorization: Bearer your_jwt_token

Step 3: Refresh When Needed

Refresh your access token using the refresh token:

POST /api/auth/refresh

{
  "refreshToken": "your_refresh_token"
}

Legacy Authentication Methods

Method 1: Authorization Header (Recommended)

Include your API key in the Authorization header using the Bearer token format:

Authorization: Bearer YOUR_API_KEY

Method 2: X-RapidAPI-Key Header

For RapidAPI integration, use the X-RapidAPI-Key header:

X-RapidAPI-Key: YOUR_RAPIDAPI_KEY

Method 3: Query Parameter (Testing Only)

For quick testing, you can include the API key as a query parameter:

https://screenpick.fun/api/search?apiKey=YOUR_API_KEY&q=action+movies

⚠️ Not recommended for production use due to potential exposure in logs

🔒 Security Best Practices

•Never expose API keys in client-side code – Always make API calls from your server
•Store API keys as environment variables – Don't hardcode them in your source code
•Implement rate limiting on your end to avoid hitting API limits unexpectedly
•Monitor your usage regularly through the RapidAPI dashboard
•Rotate API keys periodically for enhanced security

Example Authentication Headers

cURL:

curl -H "Authorization: Bearer your_api_key_here"

JavaScript (fetch):

headers: { 'Authorization': 'Bearer your_api_key_here' }

Python (requests):

headers = {'Authorization': 'Bearer your_api_key_here'}

Rate Limits

To ensure fair usage and maintain optimal service performance for all users, the Screenpick API implements intelligent rate limiting. Our rate limits are designed to accommodate both casual developers and high-volume enterprise applications.

How Rate Limiting Works

Sliding Window

We use a sliding window approach that provides more flexible usage patterns compared to fixed windows.

Per-Key Tracking

Rate limits are tracked individually for each API key, ensuring your usage doesn't affect others.

Rate Limit Tiers

Plan	Daily Requests	Per Minute	Features	Best For	Price
Basic	20 requests	1,000 requests per hour	All endpoints	Small applications	Free
Pro	2,500 requests	1,000 requests per hour	Priority support	Production apps	$5/mo
Mega	10,000 requests	4,500 requests per hour	Priority support	Large apps	$15/mo
Ultra	30,000	4,500 requests per hour	Direct Support	High-volume enterprise	$30/mo
Custom	Unlimited*	Custom	Dedicated support, SLA, custom features	Enterprise, partners	Contact Us

Rate Limit Headers

Every API response includes rate limit information in the headers:

X-RateLimit-LimitDaily limit
X-RateLimit-RemainingRemaining requests
X-RateLimit-ResetReset timestamp
X-RateLimit-WindowWindow period

Handling Rate Limits

Best practices for rate limit management:

•Check rate limit headers in responses
•Implement exponential backoff for 429 errors
•Cache responses when possible
•Use batch requests for multiple queries

⚡ Rate Limit Response (HTTP 429)

When you exceed your rate limit, you'll receive a 429 Too Many Requests response:

{
  "error": "Rate limit exceeded",
  "message": "You have exceeded your daily request limit. Please upgrade your plan or try again tomorrow.",
  "limit": 15,
  "remaining": 0,
  "resetTime": "2024-01-01T00:00:00Z"
}

Endpoints

GET/api/search

Get AI Movie Recommendations

Generate personalized movie recommendations using advanced AI. Simply describe what you're looking for, and our intelligent system will suggest movies tailored to your preferences, mood, or specific criteria.

Parameters

Name	Type	Location	Required	Description
`q`	string	query	Yes	Natural language query describing the type of movies you want. Examples: 'romantic comedies from the 90s', 'sci-fi movies with time travel', 'feel-good animated movies for kids'. Maximum length: 300 characters.
`Authorization`	string	header	No	Optional. Provide a JWT Bearer token (Authorization: Bearer <token>) or X-RapidAPI-Key for higher rate limits and access to additional features. Anonymous requests are allowed with reduced limits.

Response Format

JSON Response

{
  "success": true,
  "query": "romantic comedies from the 90s",
  "movies": [
    {
      "adult": false,
      "backdrop_path": "/wj2nLa0vfS0SLu2vJ6ABTRhMrok.jpg",
      "genre_ids": [
        35,
        10749
      ],
      "id": 334541,
      "original_language": "en",
      "original_title": "Manchester by the Sea",
      "overview": "After his older brother passes away, Lee Chandler is forced to return home to care for his 16-year-old nephew...",
      "popularity": 37.713,
      "poster_path": "/o9VXYOuaJxCEKOxbA86xqtwmqYn.jpg",
      "release_date": "2016-11-18",
      "title": "Manchester by the Sea",
      "video": false,
      "vote_average": 7.5,
      "vote_count": 5868
    }
  ],
  "total": 10,
  "requestId": "5a3c2f1e-1234-4567-89ab-abcdef012345",
  "timestamp": "2025-09-17T12:34:56.789Z",
  "authMethod": "jwt",
  "userPlan": "basic"
}

Code Examples

curl -X GET "https://screenpick.fun/api/search?q=romantic%20comedies%20from%20the%2090s" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

GET/api/getID

Get Movie Database IDs

Retrieve TMDb and IMDb identifiers for movies by title. This endpoint searches our comprehensive movie database and returns matching entries with their corresponding database IDs.

Parameters

Name	Type	Location	Required	Description
`title`	string	query	Yes	The movie title to search for. Partial matches are supported (e.g., 'La La Land', 'Inception', 'The Dark Knight').
`Authorization`	string	header	Yes	Bearer token for API authentication or X-RapidAPI-Key header.

Response Format

JSON Response

[
  {
    "title": "La La Land (2016)",
    "imdb": "tt3783958",
    "tmdb": "313369"
  },
  {
    "title": "La La Land (Short 2014)",
    "imdb": "tt4282966",
    "tmdb": "285473"
  }
]

Code Examples

curl -X GET "https://screenpick.fun/api/getID?title=La%20La%20Land" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/api/ping

Health Check

Simple endpoint to check if the API is running and accessible. Returns the current status of the service.

Parameters

No parameters required for this endpoint.

Response Format

JSON Response

{
  "status": "ok"
}

Code Examples

curl -X GET "https://screenpick.fun/api/ping"

POST/api/auth/login

JWT Authentication - Login

Exchange your API key for JWT tokens. This provides enhanced security with stateless authentication, automatic token expiration, and refresh capabilities.

Parameters

Name	Type	Location	Required	Description
`apiKey`	string	body	Yes	Your API key obtained from RapidAPI marketplace.
`email`	string	body	No	Optional email address for user identification.

Response Format

JSON Response

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": "24h",
    "tokenType": "Bearer",
    "user": {
      "userId": "user_12345678",
      "email": "user@example.com",
      "plan": "basic",
      "permissions": [
        "read",
        "search",
        "details"
      ],
      "rateLimit": {
        "requests": 100,
        "window": "1h"
      }
    }
  }
}

Code Examples

undefined

POST/api/auth/refresh

JWT Authentication - Refresh Token

Refresh your access token using a refresh token. This extends your session without requiring re-authentication with your API key.

Parameters

Name	Type	Location	Required	Description
`refreshToken`	string	body	Yes	The refresh token obtained from the login endpoint.

Response Format

JSON Response

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": "24h",
    "tokenType": "Bearer"
  }
}

Code Examples

undefined

GET/api/auth/validate

JWT Authentication - Validate Token

Validate your JWT token and retrieve user information. Use this to check if your token is still valid and get current user details.

Parameters

Name	Type	Location	Required	Description
`Authorization`	string	header	Yes	Bearer token for authentication (Authorization: Bearer YOUR_JWT_TOKEN).

Response Format

JSON Response

{
  "success": true,
  "data": {
    "valid": true,
    "user": {
      "userId": "user_12345678",
      "email": "user@example.com",
      "plan": "basic",
      "permissions": [
        "read",
        "search",
        "details"
      ],
      "rateLimit": {
        "requests": 100,
        "window": "1h"
      }
    },
    "isLegacyAuth": false,
    "expiresAt": "2025-09-17T12:00:00.000Z"
  }
}

Code Examples

undefined

Error Handling

The Screenpick API uses conventional HTTP response codes to indicate the success or failure of requests. Our error responses include detailed information to help you quickly identify and resolve issues.

HTTP Status Codes

Code	Status	Description
`200`	OK	Request completed successfully
`400`	Bad Request	Invalid request parameters or malformed request
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	Valid API key but insufficient permissions
`404`	Not Found	Requested resource or endpoint doesn't exist
`429`	Too Many Requests	Rate limit exceeded - slow down your requests
`500`	Internal Server Error	Something went wrong on our servers
`503`	Service Unavailable	API is temporarily down for maintenance

Error Response Format

When an error occurs, the API returns a structured JSON response with detailed error information to help you understand and resolve the issue quickly:

Standard Error Response

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "The request was invalid. Please check your parameters.",
    "details": "The 'q' parameter is required for movie recommendations.",
    "timestamp": "2024-01-15T10:30:00Z",
    "requestId": "req_abc123def456"
  }
}

Common Error Codes

missing_parameter - Required parameter not provided
invalid_api_key - API key is malformed or invalid
rate_limit_exceeded - Too many requests sent
service_unavailable - AI service temporarily down
query_too_long - Search query exceeds maximum length

Error Handling Best Practices

•Always check the HTTP status code first
•Parse the error response JSON for detailed information
•Implement exponential backoff for 429 and 5xx errors
•Log the requestId for support tickets
•Show user-friendly messages based on error types

Example Error Handling Code

async function handleApiResponse(response) {
  if (!response.ok) {
    const errorData = await response.json();
    
    switch (response.status) {
      case 400:
        throw new Error(`Bad Request: ${errorData.error.message}`);
      case 401:
        throw new Error('Invalid API key. Please check your credentials.');
      case 429:
        const retryAfter = response.headers.get('Retry-After') || 60;
        throw new Error(`Rate limit exceeded. Retry after ${retryAfter} seconds.`);
      case 500:
        throw new Error('Server error. Please try again later.');
      default:
        throw new Error(`API Error: ${errorData.error.message}`);
    }
  }
  
  return await response.json();
}

Ready to Build Something Amazing?

Join thousands of developers who are already using Screenpick to power their movie recommendation features. Get started with our free tier and scale as you grow.

✅ Free Tier Available

15 requests/day to get started

⚡ Fast Integration

RESTful API with SDKs

🧠 AI-Powered

Natural language processing

Need help getting started? Check out our quickstart guide or contact our support team.

Why Choose Our API

Developer-First Movie Recommendation API

Built for developers who need reliable, fast, and intelligent movie recommendations. Our API combines cutting-edge AI with developer-friendly design.

Simple Integration

RESTful API with clear endpoints and comprehensive documentation for quick implementation

Lightning Fast

Sub-second response times with globally distributed infrastructure and optimized caching

Enterprise Security

API key authentication, rate limiting, and HTTPS encryption for secure data transmission

Global CDN

Worldwide availability with 99.9% uptime SLA and automatic failover protection

Advanced AI

Rich Metadata

Comprehensive movie information including ratings, genres, cast, and detailed descriptions

Ready to discover your next favorite movie?

Join thousands of movie lovers finding perfect recommendations

DeveloperDocumentation

Screenpick APIDocumentation

Documentation

Endpoints

Introduction

What Makes Screenpick Special

Perfect For Developers

Enterprise Ready

API Architecture

Base URL

💡 Pro Tip

Authentication

🔑 New: JWT Authentication

Getting Started

Authentication Methods

JWT Authentication Flow

Step 1: Login with API Key

Step 2: Use JWT Token

Step 3: Refresh When Needed

Legacy Authentication Methods

Method 1: Authorization Header (Recommended)

Method 2: X-RapidAPI-Key Header

Method 3: Query Parameter (Testing Only)

🔒 Security Best Practices

Example Authentication Headers

Rate Limits

How Rate Limiting Works

Sliding Window

Per-Key Tracking

Rate Limit Tiers

Rate Limit Headers

Handling Rate Limits

⚡ Rate Limit Response (HTTP 429)

Endpoints

Get AI Movie Recommendations

Parameters

Response Format

Code Examples

Get Movie Database IDs

Parameters

Response Format

Code Examples

Health Check

Parameters

Response Format

Code Examples

JWT Authentication - Login

Parameters

Response Format

Code Examples

JWT Authentication - Refresh Token

Parameters

Response Format

Code Examples

JWT Authentication - Validate Token

Parameters

Response Format

Code Examples

Error Handling

HTTP Status Codes

Error Response Format

Common Error Codes

Error Handling Best Practices

Example Error Handling Code

Ready to Build Something Amazing?

Developer-First Movie Recommendation API

Simple Integration

Lightning Fast

Enterprise Security

Global CDN

Advanced AI

Rich Metadata

Developer
Documentation

Screenpick API
Documentation