Simkl Getting Started: API Access & First Request (2026)

Getting started overview

Integrating with the Simkl API enables applications to manage user watch history, track TV show and movie progress, and access media metadata. The process typically involves creating a Simkl account, upgrading to a VIP subscription to gain API access, obtaining an API key and user access token, and then constructing authenticated API requests. Simkl's API is RESTful, returning data in JSON format, and is designed for developers building custom media-related applications or integrations.

This guide focuses on the foundational steps required to make a successful first API call, covering account setup, credential retrieval, and an example request using cURL. For detailed endpoint specifications and advanced usage, refer to the official Simkl API documentation.

Quick reference steps

Create an account and get keys

To begin using the Simkl API, you must first establish a Simkl user account and then upgrade it to a VIP subscription. API access is exclusive to VIP members.

1. Sign up for Simkl

1. Navigate to the Simkl homepage.
2. Click on the "Sign Up" or "Join" option.
3. Follow the prompts to create a new account, typically requiring an email address and password.

2. Upgrade to Simkl VIP

API access is a feature of Simkl VIP accounts. After creating your free account:

1. Log in to your newly created Simkl account.
2. Visit the Simkl VIP pricing page.
3. Select a VIP plan (starting at $0.99/month) and complete the subscription process. This will enable API access for your account.

3. Obtain your API Key

Once your account is a VIP member, you can generate your API Key:

1. Log in to your Simkl account.
2. Navigate to your account settings or the developer section, which is typically linked from the Simkl API documentation.
3. Look for an option to "Generate API Key" or "Developer Settings."
4. Copy the generated API Key. This key identifies your application and should be kept secure.

4. Generate a User Access Token

Most Simkl API endpoints that access user-specific data (like watch history or personal lists) require an additional user access token. Simkl uses OAuth 2.0 for user authorization, which involves a multi-step process to obtain this token. For your first request, you might use a simplified flow or a temporary token if available in the developer settings.

The standard OAuth 2.0 flow involves:

1. Directing the user to Simkl's authorization page.
2. The user granting permission to your application.
3. Simkl redirecting the user back to your application with an authorization code.
4. Your application exchanging this code for an access token and refresh token.

For initial testing, Simkl may provide a way to manually generate a personal access token from your account settings under the User Access Token section of their API documentation. This token is typically valid for a limited time or until revoked and is suitable for development and testing purposes.

Your first request

With your API Key and a user access token, you can now make your first authenticated request. We will use cURL for this example, which is a common command-line tool for making HTTP requests.

Example: Get User Profile

Let's try to retrieve the current user's profile information. This endpoint typically requires both your API Key and a user access token.

curl -X GET \
  'https://api.simkl.com/users/profile?client_id=YOUR_API_KEY&access_token=YOUR_USER_ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

Replace the placeholders:

• YOUR_API_KEY: Your unique API Key obtained from your Simkl developer settings.
• YOUR_USER_ACCESS_TOKEN: The user-specific access token you generated.

Expected Response

A successful response will return JSON data containing the user's profile information, similar to this (actual fields may vary):

{
  "user": {
    "id": 12345,
    "name": "YourUserName",
    "email": "[email protected]",
    "join_date": "2023-01-15T10:00:00Z",
    "vip": true,
    "country": "US"
  }
}

If you receive a 200 OK status code and a JSON object with your profile details, your first request was successful. This confirms your API Key and access token are correctly configured.

Common next steps

After successfully making your first request, consider these common next steps for further integration:

• Explore Endpoints: Review the Simkl API documentation to understand available endpoints for tracking watch history, managing watchlists, searching for content, and more.
• Implement OAuth 2.0: For production applications, implement the full OAuth 2.0 flow to securely obtain and refresh user access tokens without manual intervention. This ensures users can authorize your application safely.
• Error Handling: Implement robust error handling in your application to gracefully manage API rate limits, invalid credentials, or other API-specific errors. The MDN Web Docs on HTTP status codes provide a general reference for common API response codes.
• Rate Limits: Understand and respect Simkl's API rate limits to prevent your application from being temporarily blocked. Details on rate limits are typically found in the API documentation.
• Webhooks: Investigate if Simkl offers webhooks for real-time notifications of user activity or data changes, which can reduce the need for constant polling.
• SDKs: While Simkl does not provide official SDKs, consider building a lightweight wrapper in your preferred programming language to simplify API interactions.

Troubleshooting the first call

If your first API call does not return the expected successful response, review these common issues:

• Invalid API Key (client_id): Double-check that you have copied your API Key correctly and that it is included in the request URL or header as specified by Simkl's documentation. Ensure your account is a Simkl VIP member, as API access is restricted to this tier.
• Invalid User Access Token (access_token): Verify that the user access token is correct and has not expired. If you're using a manually generated token, confirm its validity period. For OAuth-based tokens, ensure the authorization flow completed successfully.
• Incorrect Endpoint or Method: Confirm that the URL for the endpoint (e.g., /users/profile) is accurate and that you are using the correct HTTP method (e.g., GET for retrieving data).
• Missing Headers: Ensure that required HTTP headers, such as Content-Type: application/json, are included in your request if specified by the API documentation.
• Network Issues: Check your internet connection and ensure there are no firewalls or proxies blocking your request to api.simkl.com.
• Rate Limiting: If you've made many requests in a short period, you might have hit a rate limit. Wait a few minutes and try again. Simkl's API documentation will detail their specific rate limit policies.
• API Documentation: Refer to the Simkl API documentation for specific error codes and their meanings. Error responses from the API often contain messages that can help diagnose the problem.