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' '404': description: Title not found '400': description: Request params are not correct '500': description: Unknown server error '204': description: No title found /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' '404': description: User not found '400': description: Request params are not correct '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: # example base64( {id: 1, param: 2019}) 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 # - creation_date 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