Ratings
Star or number ratings on anything on your site: games, posts, recipes, products. Each visitor gives one score per item (1 to 5, or up to 10); rating again replaces it. Visitors see the average, the number of ratings and their own score; you see what is rated best. Set up via endpoints; no code needed.
Endpoints (8)
Create a rating type, e.g. "game-score" with a 1-10 scale or "stars" with 1-5. access "verified" (default): signed-in visitors or tenants only, truly one score per person. access "anonymous": any visitor, tied to the browser session (a new session can rate again). Ratings do not check that the item exists; use target_types to restrict what can be rated.
| Field | Type | Required | Description |
|---|---|---|---|
kind_key |
string | ✓ Yes | Short id, lowercase letters, digits, - and _. Example: "game-score". |
label |
string | ✓ Yes | Human-readable name. |
max_score |
integer | No | Highest score, 2-10. Default 5. Fixed after the first rating. |
access |
string | No | "verified" (default) or "anonymous". |
target_types |
array | No | Allowed item types, e.g. ["game"]. Default: any type. |
public_summary |
boolean | No | Show averages and counts to visitors. Default true. |
per_actor_hourly |
integer | No | Max new ratings per visitor per hour (0 = off, max 1000). Default 0. |
per_ip_hourly |
integer | No | Anonymous only: max new ratings per IP address per hour (0 = off, max 1000). Default 60. |
Change a rating type. Only send what changes. max_score is fixed after the first rating. Set is_active false to pause.
| Field | Type | Required | Description |
|---|---|---|---|
kind_key |
string | ✓ Yes | |
label |
string | No | |
max_score |
integer | No | |
access |
string | No | |
target_types |
array | No | |
public_summary |
boolean | No | |
per_actor_hourly |
integer | No | |
per_ip_hourly |
integer | No | |
is_active |
boolean | No |
All rating types of this project with their settings, plus the platform limits.
No input parameters required.
Items with the highest average for a rating type, e.g. the best rated games. Only items with at least min_count ratings.
| Field | Type | Required | Description |
|---|---|---|---|
kind_key |
string | ✓ Yes | |
target_type |
string | No | |
min_count |
integer | No | Default 3. |
limit |
integer | No | Default 20, max 100. |
Remove all ratings of one type from one item and reset its numbers, e.g. after abuse or when the item is deleted.
| Field | Type | Required | Description |
|---|---|---|---|
kind_key |
string | ✓ Yes | |
target_type |
string | ✓ Yes | |
target_id |
string | ✓ Yes |
The current visitor gives an item a score from 1 to max_score. Rating the same item again replaces the score. Returns the visitor's own score and, when public, count, average and score_100. Only visitors can rate.
| Field | Type | Required | Description |
|---|---|---|---|
kind_key |
string | ✓ Yes | |
target_type |
string | ✓ Yes | e.g. "game", "post", "recipe". |
target_id |
string | ✓ Yes | Id of the item. |
score |
integer | ✓ Yes | Whole number from 1 to max_score. |
The current visitor removes their score from an item. Calling it without a score changes nothing.
| Field | Type | Required | Description |
|---|---|---|---|
kind_key |
string | ✓ Yes | |
target_type |
string | ✓ Yes | |
target_id |
string | ✓ Yes |
count, average, score_100 (1 = 0, max_score = 100) and the visitor's own score ("mine") for up to 100 items in one call. Use it once per page for all items shown.
| Field | Type | Required | Description |
|---|---|---|---|
kind_key |
string | ✓ Yes | |
targets |
array | ✓ Yes | List of items, e.g. [{"type":"game","id":"540"},{"type":"game","id":"612"}]. Max 100. |
MCP Tool Names
When using this integration through an AI assistant (Claude, ChatGPT, Cursor, etc.), the endpoints are available as MCP tools:
| Endpoint | MCP Tool Name |
|---|---|
| define-kind | ratings_define_kind |
| update-kind | ratings_update_kind |
| get-config | ratings_get_config |
| top-rated | ratings_top_rated |
| clear-target | ratings_clear_target |
| rate | ratings_rate |
| unrate | ratings_unrate |
| get-summary | ratings_get_summary |
Website