openapi: 3.0.4 info: title: 'Titles, Users, Reviews, Tags, and Media API' version: 1.0.0 servers: - url: /api/v1 paths: /titles: get: summary: Get titles parameters: - $ref: '#/components/parameters/cursor' - $ref: '#/components/parameters/title_sort' - in: query name: sort_forward schema: type: boolean default: true - in: query name: word schema: type: string - in: query name: status schema: $ref: '#/components/schemas/TitleStatus' - in: query name: rating schema: type: number format: double - in: query name: release_year schema: type: integer format: int32 - in: query name: release_season schema: $ref: '#/components/schemas/ReleaseSeason' - in: query name: limit schema: type: integer format: int32 default: 10 - in: query name: offset schema: type: integer format: int32 default: 0 - in: query name: fields schema: type: string default: all responses: '200': description: List of titles with cursor content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Title' description: List of titles cursor: $ref: '#/components/schemas/CursorObj' required: - data - cursor '204': description: No titles found '400': description: Request params are not correct '500': description: Unknown server error '/titles/{title_id}': get: summary: Get title description parameters: - in: path name: title_id required: true schema: type: integer format: int64 - in: query name: fields schema: type: string default: all responses: '200': description: Title description content: application/json: schema: $ref: '#/components/schemas/Title' '204': description: No title found '400': description: Request params are not correct '404': description: Title not found '500': description: Unknown server error '/users/{user_id}': get: summary: Get user info parameters: - in: path name: user_id required: true schema: type: string - in: query name: fields schema: type: string default: all responses: '200': description: User info content: application/json: schema: $ref: '#/components/schemas/User' '400': description: Request params are not correct '404': description: User not found '500': description: Unknown server error '/users/{user_id}/titles/': get: summary: Get user titles parameters: - $ref: '#/components/parameters/cursor' - in: path name: user_id required: true schema: type: string - in: query name: word schema: type: string - in: query name: status schema: $ref: '#/components/schemas/TitleStatus' - in: query name: watch_status schema: $ref: '#/components/schemas/UserTitleStatus' - in: query name: rating schema: type: number format: double - in: query name: release_year schema: type: integer format: int32 - in: query name: release_season schema: $ref: '#/components/schemas/ReleaseSeason' - in: query name: limit schema: type: integer format: int32 default: 10 - in: query name: fields schema: type: string default: all responses: '200': description: List of user titles content: application/json: schema: type: array items: $ref: '#/components/schemas/UserTitle' '204': description: No titles found '400': description: Request params are not correct '500': description: Unknown server error components: parameters: cursor: in: query name: cursor required: false schema: type: string title_sort: in: query name: sort required: false schema: $ref: '#/components/schemas/TitleSort' schemas: CursorObj: type: object required: - id properties: id: type: integer format: int64 param: type: string TitleSort: type: string description: Title sort order default: id enum: - id - year - rating - views Image: type: object properties: id: type: integer format: int64 storage_type: type: string image_path: type: string TitleStatus: type: string description: Title status enum: - finished - ongoing - planned ReleaseSeason: type: string description: Title release season enum: - winter - spring - summer - fall UserTitleStatus: type: string description: User's title status enum: - finished - planned - dropped - in-progress Review: type: object additionalProperties: true Tag: type: object description: 'A localized tag: keys are language codes (ISO 639-1), values are tag names' additionalProperties: type: string example: en: Shojo ru: Сёдзё ja: 少女 Tags: type: array description: Array of localized tags items: $ref: '#/components/schemas/Tag' example: - en: Shojo ru: Сёдзё ja: 少女 - en: Shounen ru: Сёнен ja: 少年 Studio: type: object required: - id - name properties: id: type: integer format: int64 name: type: string poster: $ref: '#/components/schemas/Image' description: type: string Title: type: object required: - id - title_names - tags properties: id: type: integer format: int64 description: Unique title ID (primary key) example: 1 title_names: type: object description: 'Localized titles. Key = language (ISO 639-1), value = list of names' additionalProperties: type: array items: type: string example: Attack on Titan minItems: 1 example: - Attack on Titan - AoT example: en: - Attack on Titan - AoT ru: - Атака титанов - Титаны ja: - 進撃の巨人 studio: $ref: '#/components/schemas/Studio' tags: $ref: '#/components/schemas/Tags' poster: $ref: '#/components/schemas/Image' title_status: $ref: '#/components/schemas/TitleStatus' rating: type: number format: double rating_count: type: integer format: int32 release_year: type: integer format: int32 release_season: $ref: '#/components/schemas/ReleaseSeason' episodes_aired: type: integer format: int32 episodes_all: type: integer format: int32 episodes_len: type: object additionalProperties: type: number format: double additionalProperties: true User: type: object properties: id: type: integer format: int64 description: Unique user ID (primary key) example: 1 avatar_id: type: integer format: int64 description: ID of the user avatar (references images table) example: null mail: type: string format: email description: User email example: john.doe@example.com nickname: type: string description: Username (alphanumeric + _ or -) maxLength: 16 example: john_doe_42 disp_name: type: string description: Display name maxLength: 32 example: John Doe user_desc: type: string description: User description maxLength: 512 example: Just a regular user. creation_date: type: string format: date-time description: Timestamp when the user was created example: '2025-10-10T23:45:47.908073Z' required: - user_id - nickname UserTitle: type: object required: - user_id - title_id - status properties: user_id: type: integer format: int64 title_id: type: integer format: int64 status: $ref: '#/components/schemas/UserTitleStatus' rate: type: integer format: int32 review_id: type: integer format: int64 ctime: type: string format: date-time additionalProperties: true