Ratings API Endpoint Guide v2025-05-22

← Back to OAuth 2.0 Authorization Guide

Rate Limit: You can perform up to 10 requests per minute on this endpoint.
Exceeding the limit will result in HTTP 429 (Too Many Requests).

Important: API requests must include a meaningful User-Agent header. Requests with missing or generic user agents may be blocked with HTTP 403 due to automated abuse protection, and may temporarily result in your IP address being denied further access. Please identify your application clearly by using a custom user agent string, such as: MyApp/1.0 (contact@example.com).

Authentication

This endpoint requires a valid Access Token with the ratings.anime or ratings.manga scope, depending on the media type.

General Information

The {mediaType} parameter must be replaced by anime or manga depending on the type of entry you want to manage.

Endpoints

Get Rating (Single Entry)

Retrieves the authenticated user’s rating for the specified ID.

GET https://api.anisearch.com/v1/my/{mediaType}/{id}/ratings
Authorization: Bearer YOUR_ACCESS_TOKEN

Get Ratings (All Entries)

Retrieves all ratings for the authenticated user within the given media type.

GET https://api.anisearch.com/v1/my/{mediaType}/ratings
Authorization: Bearer YOUR_ACCESS_TOKEN

Successful Response

The following examples show the response structure for anime and manga entries side by side. The response is always an array, even if only a single entry is returned.

Anime Example Manga Example

Anime Example	Manga Example
`[ { "id-anisearch": 5048, "id-myanimelist": 5114, "status": "completed", "is_visible": true, "public_rating": 9, "public_fraction": 0, "personal_rating": 85, "start_date": "2023-01-01", "end_date": "2023-02-01", "notes": "One of my favorites!", "priority": 2, "episodes_watched": 24, "is_rewatching": false, "times_rewatched": 0, "rewatch_desire": 3 } ]`	`[ { "id-anisearch": 724, "id-myanimelist": 13, "status": "completed", "is_visible": true, "public_rating": 9, "public_fraction": 0, "personal_rating": 85, "start_date": "2023-01-01", "end_date": "2023-02-01", "notes": "One of my favorites!", "priority": 2, "episodes_watched": 24, "is_reread": false, "times_reread": 0, "reread_desire": 3 } ]`

[
  {
    "id-anisearch": 5048,
    "id-myanimelist": 5114,
    "status": "completed",
    "is_visible": true,
    "public_rating": 9,
    "public_fraction": 0,
    "personal_rating": 85,
    "start_date": "2023-01-01",
    "end_date": "2023-02-01",
    "notes": "One of my favorites!",
    "priority": 2,
    "episodes_watched": 24,
    "is_rewatching": false,
    "times_rewatched": 0,
    "rewatch_desire": 3
  }
]

[
  {
    "id-anisearch": 724,
    "id-myanimelist": 13,
    "status": "completed",
    "is_visible": true,
    "public_rating": 9,
    "public_fraction": 0,
    "personal_rating": 85,
    "start_date": "2023-01-01",
    "end_date": "2023-02-01",
    "notes": "One of my favorites!",
    "priority": 2,
    "episodes_watched": 24,
    "is_reread": false,
    "times_reread": 0,
    "reread_desire": 3
  }
]

Delete Rating

Deletes the authenticated user’s rating for the specified ID.

DELETE https://api.anisearch.com/v1/my/{mediaType}/{id}/ratings
Authorization: Bearer YOUR_ACCESS_TOKEN

Successful Response

{
  "success": true
}

Rate Limit: You can perform up to 10 requests per minute on this endpoint.
Exceeding the limit will result in HTTP 429 (Too Many Requests).

Upsert Rating (Create/Update)

Creates or updates the authenticated user’s rating for the specified ID. The field status is required; all other fields are optional and will be initialized with default values if omitted.

PUT https://api.anisearch.com/v1/my/{mediaType}/{id}/ratings
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

Request Body

Field	Description
`status`	`string` — Required. One of: `ongoing`, `completed`, `on_hold`, `dropped`, `not_interested` or `bookmark`.
Optional Fields (all below can be omitted; omitted fields won’t affect existing values on update)
`use_myanimelist_id`	`boolean` — Set to `true` if the `id` in the URL refers to a MyAnimeList ID instead of aniSearch’s internal ID.
`is_visible`	`boolean` — If true, the rating is visible to others; if false, it remains private. Default is `true`.
`public_rating`	`integer` — Public score (0–10).
`public_fraction`	`integer` — Decimal of the public score (0–9).
`personal_rating`	`integer` — Personal score (0–100). This score is for personal use only and does not affect the overall rating of the title.
`episodes_watched` (anime)	`integer` — Episodes watched.
`chapters_read` (manga)	`integer` — Chapters read.
`volumes_read` (manga)	`integer` — Volumes read.
`start_date`	`string` — Date when viewing started (YYYY-MM-DD).
`end_date`	`string` — Date when viewing ended (YYYY-MM-DD).
`is_rewatching` `is_rereading`	`boolean` — Currently rewatching/rereading.
`times_rewatched` `times_reread`	`integer` — Times rewatched/reread.
`rewatch_desire` `reread_desire`	`integer` — Desire to rewatch or reread (0–5), where 0 means no interest and 5 means very high interest.
`notes`	`string` — User notes or comments.
`priority`	`integer` — Priority (0–3), where 0 means no priority and 3 means highest priority.
`touch`	`boolean` — If true, the entry’s last modified timestamp will be updated to the current time. If omitted or false, the timestamp remains unchanged.

Successful Response

{
  "success": true
}

Rate Limit: You can perform up to 100 requests per 2 minutes on this endpoint.
Exceeding the limit will result in HTTP 429 (Too Many Requests).