Recomms AI API Developer Guide

Introduction

This guide provides a comprehensive overview of the Recomms AI API, which offers various endpoints for managing items, users, interactions, business rules, and recommendations. The API is designed to help developers integrate Recomms AI's recommendation system into their applications, enabling personalized and efficient content or product recommendations.

Base URL

The base URL for all API endpoints is:

https://api.recomms.ai

Always check for the latest version and any updates to ensure you're using the most current features and best practices.

Authentication

The Recomms AI API uses API keys for authentication. To access the API, you need to include your API key in the header of each request. Here's how to do it:

Obtain your API key from the Recomms AI dashboard or by contacting the Recomms AI support team.

Include the API key in the Authorization header of your HTTP requests.

Example:

Authorization: Bearer YOUR_API_KEY_HERE

Replace YOUR_API_KEY_HERE with your actual API Secret key.

Important security notes:

Keep your API key confidential. Do not share it or expose it in client-side code.

If you suspect your API key has been compromised, contact Recomms AI support immediately to have it revoked and replaced.

Consider using environment variables or secure secret management systems to store your API key, rather than hardcoding it in your application.

Rate Limiting

The Recomms AI API implements rate limiting to ensure fair usage and system stability. The current limits are:

Pay as you go:

100 requests per second per API key

Custom plan:

Tailored requests per second per API key

If you exceed these limits, you'll receive a 429 (Too Many Requests) response. The response will include headers indicating your current rate limit status.

If you need higher limits for your application, please contact Recomms AI support to discuss your requirements.

Common Parameters

Many endpoints include a database path parameter. This parameter is required and represents the ID of the database you're operating on. Ensure you have the correct database ID before making any requests. This allows the API to isolate data and operations for different applications or environments you might be managing.

Endpoints

Items

The Items section of the API allows you to manage the items in your recommendation system. These could be products, articles, videos, or any other type of content that you want to recommend to users.

Key Concepts:

Item ID: A unique identifier for each item in your system. This could be a SKU, article number, or any other unique identifier you use in your system.

Side Info: Additional properties or metadata associated with items. This could include things like category, price, release date, or any other attributes relevant to your items.

Important Operations:

Create: Add new items to your database.

Retrieve: Fetch details of existing items, either individually or in batches.

Update: Modify information for existing items.

Delete: Remove items from your database.

Manage custom properties (side info): Add, update, or remove additional attributes for items.

Reset: Clear all items from a database, useful for testing or major system updates.

Use Cases:

Populating your recommendation system with products or content when first setting up or when adding new inventory.

Updating item information (e.g., price changes, availability updates, content modifications).

Adding custom properties to items for better categorization, filtering, or to influence recommendation algorithms.

Removing discontinued or irrelevant items from your recommendation pool.

Users

The Users section is similar to the Items section, but it deals with managing user profiles in your recommendation system.

Key Concepts:

User ID: A unique identifier for each user in your system. This could be a customer number, email address, or any other unique identifier you use.

User Side Info: Additional properties or metadata associated with users. This might include demographics, preferences, or behavioral data.

Important Operations:

Create: Add new user profiles to your system.

Retrieve: Fetch user information, either for individual users or in batches.

Update: Modify existing user profiles.

Delete: Remove users from your system.

Manage custom properties (side info): Add, update, or remove additional attributes for users.

Reset: Clear all user data from a database, useful for testing or major system resets.

Use Cases:

Creating user profiles when new users sign up for your service.

Updating user information as they interact with your system or provide additional data.

Adding custom properties to users for more personalized recommendations (e.g., preferences, past behavior).

Removing inactive users or for compliance with data protection regulations.

Interactions

The Interactions section is crucial for recording user behavior, which forms the basis of the recommendation system's learning process.

Key Concepts:

Interaction Types: Different ways users can interact with items. The API supports several types:

detailviews: Record time spent viewing an item

purchases: Record a purchase of an item

ratings: Record a user's rating of an item

cartadditions: Record adding an item to the cart

bookmarks: Record bookmarking an item

viewportions: Record the portion of an item viewed

Timestamp: When the interaction occurred. This is crucial for understanding user behavior over time.

Cascade Create: An option to automatically create missing users or items when recording an interaction.

Important Operations:

Record single interaction: Log individual user actions.

Record multiple interactions: Batch log multiple actions for efficiency.

Retrieve interaction history: Fetch past interactions, useful for analysis or debugging.

Delete specific interactions: Remove individual interaction records if needed.

Reset all interactions: Clear all interaction data from a database.

Use Cases:

Tracking user behavior in real-time as they interact with your platform.

Analyzing user engagement patterns over time.

Removing erroneous interactions or conducting A/B tests by selectively deleting interactions.

Bulk uploading historical interaction data to initialize or update the recommendation model.

Business Rules

Business Rules allow you to customize the behavior of the recommendation system, ensuring that recommendations align with your business logic and constraints.

Key Concepts:

Rule Types:

Boosters: These rules increase the likelihood of certain items being recommended. They're used to promote specific items or categories.

Filters: These rules exclude certain items from recommendations. They're used to prevent inappropriate or irrelevant recommendations.

Resource: Specifies whether the rule applies to 'users' or 'items'.

Field: The specific attribute of the resource that the rule evaluates (e.g., 'category', 'age', 'price').

Condition: The logical test applied to the field. Supported conditions include:

>, <, >=, <=: Numerical comparisons

==: Exact match

in, not in: Membership in a set

contains, not contains: String containment

Value: The benchmark for the condition. Can be a static value or a dynamic placeholder (${value}) that's resolved at runtime.

Enabled: A boolean flag to easily turn rules on or off without deleting them.

Default: Indicates whether this is a default rule that should always be applied.

Important Operations:

Create: Add new business rules to your system.

Retrieve: Fetch details of existing rules, either individually or as a list.

Update: Modify existing rules.

Delete: Remove rules from your system.

Apply: Use rules in recommendation requests by referencing their IDs.

Use Cases:

Boosting:

Promote seasonal items (e.g., boost summer clothes during summer months).

Highlight new arrivals or trending items.

Increase visibility of high-margin products.

Filtering:

Exclude out-of-stock items from recommendations.

Prevent recommending age-inappropriate content to younger users.

Remove items that a user has already purchased from their recommendations.

Personalization:

Boost items from a user's favorite brands or categories.

Filter recommendations based on user's price preferences.

Example:

Let's say you want to boost eco-friendly products for environmentally conscious users:

Create a user side info property eco_conscious (boolean).

Create an item side info property eco_friendly (boolean).

Create a business rule:

Resource: 'items'

Rule: 'booster'

Field: 'eco_friendly'

Condition: '=='

Value: 'true'

Apply this rule when getting recommendations for users with eco_conscious set to true.

This setup will increase the likelihood of eco-friendly products being recommended to environmentally conscious users, without excluding other products entirely.

Recommendations

This section provides various endpoints for generating and customizing recommendations based on user behavior and item characteristics.

Key Concepts:

User-to-Item Recommendations: Suggesting items to users based on their profile and past behavior.

Item-to-User Recommendations: Finding potential users who might be interested in a specific item.

Similar Users: Identifying users with similar tastes or behaviors, useful for expanding recommendation pools.

Prediction Scores: Numerical estimates of how likely a user is to interact positively with an item.

Search: Finding items or users based on specific criteria, often with personalized ranking.

Top Items: Identifying the most popular or relevant items across all users or within segments.

Important Operations:

Get item recommendations for a user: Suggest items a specific user might like.

Get user recommendations for an item: Find users who might be interested in a specific item.

Find similar users: Identify users with similar preferences or behaviors.

Predict scores for user-item pairs: Estimate the likelihood of positive interactions between users and items.

Search for items or users: Find resources based on various criteria, potentially personalized per user.

Get top items: Retrieve a list of the most relevant items, optionally filtered or personalized.

Use Cases:

Displaying personalized product recommendations on an e-commerce site's homepage or product pages.

Suggesting content to users in a streaming platform's UI.

Finding potential customers for a new product launch or marketing campaign.

Implementing a search feature that considers both relevance and personal preference.

Creating "trending now" or "popular in your area" sections in an app.

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of requests. Common error responses include:

400 Bad Request: The request was invalid or cannot be served. This could be due to missing required parameters or invalid data formats.

401 Unauthorized: Authentication is required and has failed or has not been provided. Check your API credentials.

404 Not Found: The requested resource could not be found. This could mean an invalid endpoint or a non-existent item/user ID.

500 Internal Server Error: The server encountered an unexpected condition that prevented it from fulfilling the request. These should be reported to the Recomms AI support team.

Error responses typically include a JSON object with status and message fields providing more details about the error. Always check for and handle these errors in your code to ensure a smooth user experience.

Pagination

Many endpoints that return lists of items support pagination. Use the page and page_size query parameters to control the number of results returned. The default page size is 20, with a maximum of 100 items per page.

Pagination is crucial for managing large datasets efficiently, ensuring quick response times and reducing server load. Always implement pagination in your applications, especially when dealing with potentially large sets of items, users, or interactions.

Side Info

Side info refers to custom properties that can be added to items or users. These properties can be used for filtering, sorting, or as part of recommendation algorithms. When creating side info, you need to specify:

key: The name of the custom property

data_type: The data type of the property (e.g., "BOOLEAN", "DOUBLE", "INT", "STRING", "TIMESTAMP", "ARRAY")

Side info allows you to enrich your item and user data, leading to more accurate and relevant recommendations. Use side info to capture any additional attributes that might be relevant to your recommendation needs, such as item categories, user preferences, or any domain-specific information.

Conclusion

The Recomms AI API offers a powerful and flexible framework for building sophisticated recommendation systems. By effectively using items, users, interactions, business rules, and the various recommendation endpoints, you can create highly personalized and relevant experiences for your users.

Key points to remember:

Always use the correct database ID in your requests to ensure you're operating on the right dataset.

Regularly record user interactions to keep your recommendation model up-to-date and accurate.

Use business rules to fine-tune recommendations according to your specific needs, balancing automation with business logic.

Leverage side info to add rich, custom data to your items and users, enhancing the quality of recommendations.

Implement proper error handling to ensure a smooth user experience and easier debugging.

Use pagination for efficient data retrieval and processing, especially when dealing with large datasets.

Experiment with different combinations of features, business rules, and recommendation types to find the optimal setup for your specific use case.

For more detailed information about request and response formats, refer to the full API specification or contact the Recomms AI support team. Remember that building an effective recommendation system is an iterative process. Continuously monitor your system's performance, gather user feedback, and refine your approach to provide the best possible recommendations for your users.

Documentation

Recomms AI API Developer Guide#

Introduction#

Base URL#

Authentication#

Rate Limiting#

Common Parameters#

Endpoints#

Items#

Key Concepts:#

Important Operations:#

Use Cases:#

Users#

Key Concepts:#

Important Operations:#

Use Cases:#

Interactions#

Key Concepts:#

Important Operations:#

Use Cases:#

Business Rules#

Key Concepts:#

Important Operations:#

Use Cases:#

Example:#

Recommendations#

Key Concepts:#

Important Operations:#

Use Cases:#

Error Handling#

Pagination#

Side Info#

Conclusion#

Recomms AI API Developer Guide

Introduction

Base URL

Authentication

Rate Limiting

Common Parameters

Endpoints

Items

Key Concepts:

Important Operations:

Use Cases:

Users

Key Concepts:

Important Operations:

Use Cases:

Interactions

Key Concepts:

Important Operations:

Use Cases:

Business Rules

Key Concepts:

Important Operations:

Use Cases:

Example:

Recommendations

Key Concepts:

Important Operations:

Use Cases:

Error Handling

Pagination

Side Info

Conclusion