Skip to main content

UserStory

This is an object representing an User's watch history. The API allows you to retrieve individual UserStory as well as a list of them using various filters. Furthermore it lets you create, update and delete an UserStory.

UserStory is used to synchronize data between AniAPI and external Anime tracking systems.

Endpoints
GET/v1/user_story/:id
GET/v1/user_story
PUT/v1/user_story
POST/v1/user_story
DELETE/v1/user_story

The UserStory object#

Attributes#

id integer#

Unique identifier for an UserStory.

user_id integer#

User external unique identifier.

anime_id string#

Anime external unique identifier.

status enum#

The UserStory's watching status.

Possible status enum values
"CURRENT": 0,"PLANNING": 1,"COMPLETED": 2,"DROPPED": 3,"PAUSED": 4,"REPEATING": 5

current_episode integer#

The UserStory's watching progress.

current_episode_ticks integer#

The UserStory's current_episode watching time in milliseconds.

Example#

UserStory object example
{  "user_id": 1,  "anime_id": 10,  "status": 2,  "current_episode": 220,  "current_episode_ticks": 0,  "id": 27}

Retrieve a specific UserStory#

GET/v1/user_story/:id

Retrieves an UserStory, based on its unique identifier.

Parameters#

No parameters.

Returns#

Returns an UserStory object if a valid identifier was provided and the authenticated User owns the rights to get it.

Try it#

This feature is not available on mobile.

Get a list of UserStory#

GET/v1/user_story

Returns a list of UserStory objects. The UserStories are returned sorted by creation_date, following descending order.

info

As default, it will return all the UserStories owned by the request's authenticated User using the user_id filter's field.

Parameters#

anime_id integer optional#

A filter on the list based on the anime_id field value.

user_id integer default#

A filter on the list based on the user_id field value.

status enum optional#

A filter on the list based on the status field value.

synced bool optional#

A filter on the list based on the synced field value. synced field indicates if an UserStory has been synchronized with User's linked trackers.

Returns#

Returns an array of UserStory objects with a size based on the filter provided.

Try it#

This feature is not available on mobile.

Create an UserStory#

PUT/v1/user_story

Creates an UserStory based on the provided values.

Parameters#

user_id integer required#

The User's id that own the UserStory.

anime_id integer required#

The UserStory's Anime.

status enum required#

The UserStory's watching status.

current_episode integer optional#

The UserStory's watching progress. Must be equal or less than the Anime's episodes_count value. When you provide a status equal to 1 or 2 this field is auto-calculated.

current_episode_ticks integer optional#

The UserStory's current_episode watching time in milliseconds.

Returns#

Returns the created UserStory object.

Example#

Example UserStory create request
fetch('https://api.aniapi.com/v1/user_story', {  method: 'PUT',  headers: {    'Authorization': 'Bearer <YOUR_JWT>',    'Content-Type': 'application/json',    'Accept': 'application/json'  },  body: {    user_id: 1,    anime_id: 10,    status: 2  }});
Example UserStory create response
{  "status_code": 200,  "message": "Story created",  "data": {    "user_id": 1,    "anime_id": 10,    "status": 2,    "current_episode": 220,    "current_episode_ticks": 0,    "id": 1  },  "version": "1"}

Update an UserStory#

POST/v1/user_story

Updates an UserStory based on the provided values.

Parameters#

id integer required#

The UserStory's unique identifier.

user_id integer required#

The User's id that owns the UserStory.

anime_id integer required#

The UserStory's Anime.

status enum required#

The UserStory's watching status.

current_episode integer required#

The UserStory's watching progress. Must be equal or less than the Anime's episodes_count value.

current_episode_ticks integer required#

The UserStory's current_episode watching time in milliseconds.

Returns#

Returns the updated UserStory object.

Example#

Example UserStory update request
fetch('https://api.aniapi.com/v1/user_story', {  method: 'POST',  headers: {    'Authorization': 'Bearer <YOUR_JWT>',    'Content-Type': 'application/json',    'Accept': 'application/json'  },  body: {    id: 27,    user_id: 1,    anime_id: 10,    status: 0,    current_episode: 140,    current_episode_ticks: 1200000  }});
Example UserStory update response
{  "status_code": 200,  "message": "Story updated",  "data": {    "user_id": 1,    "anime_id": 10,    "status": 0,    "current_episode": 140,    "current_episode_ticks": 1200000,    "id": 27  },  "version": "1"}

Delete an UserStory#

DELETE/v1/user_story

Deletes an UserStory based on the provided unique identifier.

caution

You should use this endpoint only when the User has zero linked trackers. Otherwise the UserStory will get re-imported!

Parameters#

No parameters.

Returns#

No particular return.

Example#

Example UserStory delete request
fetch('https://api.aniapi.com/v1/user_story/27', {  method: 'DELETE',  headers: {    'Authorization': 'Bearer <YOUR_JWT>',    'Content-Type': 'application/json',    'Accept': 'application/json'  }});
Example UserStory delete response
{  "status_code": 200,  "message": "Story deleted",  "data": "",  "version": "1"}