openapi: 3.1.0
info:
  title: DYO.gg API — Honkai Star Rail
  version: 1.0.0
  summary: Endpoint HSR — player, character, light cone, relic, trace tree.
servers:
  - url: https://api.dyogg.com
security:
  - bearerAuth: []
components:
  securitySchemes:
    bearerAuth: { type: http, scheme: bearer }
  schemas:
    HsrPath:
      type: string
      enum: [Destruction, Hunt, Erudition, Harmony, Nihility, Preservation, Abundance, Remembrance]
    HsrElement:
      type: string
      enum: [Physical, Fire, Ice, Lightning, Wind, Quantum, Imaginary]
    HsrPlayer:
      type: object
      properties:
        uid: { type: string }
        game: { type: string, enum: [hsr] }
        nickname: { type: string }
        level: { type: integer, minimum: 1, maximum: 70 }
        world_level: { type: integer, minimum: 0, maximum: 6 }
        signature: { type: string, nullable: true }
        profile_picture_url: { type: string, format: uri, nullable: true }
        showcase:
          type: array
          items: { $ref: '#/components/schemas/HsrShowcaseChar' }
    HsrShowcaseChar:
      type: object
      properties:
        avatar_id: { type: integer, example: 1308 }
        name: { type: string, example: Acheron }
        element:
          type: object
          properties:
            id: { type: string, example: Thunder }
            name: { $ref: '#/components/schemas/HsrElement' }
        path:
          type: object
          properties:
            id: { type: string, example: Warlock }
            name: { $ref: '#/components/schemas/HsrPath' }
        level: { type: integer, minimum: 1, maximum: 80 }
        eidolon: { type: integer, minimum: 0, maximum: 6 }
        ascension: { type: integer, minimum: 0, maximum: 6 }
        light_cone:
          type: object
          properties:
            id: { type: integer }
            name: { type: string }
            level: { type: integer }
            superimpose: { type: integer, minimum: 1, maximum: 5 }
        relics:
          type: array
          maxItems: 6
          items:
            type: object
            properties:
              slot: { type: string, enum: [head, hands, body, feet, sphere, rope] }
              set_id: { type: integer }
              level: { type: integer, minimum: 0, maximum: 15 }
              main_stat: { type: object }
              sub_stats: { type: array }
        trace_tree:
          type: array
          maxItems: 4
          items:
            type: object
            properties:
              key: { type: string, enum: [Basic, Skill, Ultimate, Talent] }
              main_skill: { type: object }
              stat_nodes: { type: array }
paths:
  /v1/player/hsr/{uid}:
    get:
      tags: [Player]
      summary: Get HSR player overview
      parameters:
        - in: path
          name: uid
          required: true
          schema: { type: string, pattern: '^[0-9]{9,10}$' }
          example: '602891308'
        - in: query
          name: provider
          schema: { type: string, enum: [enka, mihomo, auto], default: auto }
      responses:
        '200':
          description: Player
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/HsrPlayer' }
        '404': { description: UID not found }
  /v1/character/hsr/{avatar_id}:
    get:
      tags: [Character]
      summary: HSR character metadata
      parameters:
        - in: path
          name: avatar_id
          required: true
          schema: { type: integer, example: 1308 }
      responses:
        '200': { description: OK }
  /v1/light-cone/hsr/{light_cone_id}:
    get:
      tags: [Weapon]
      summary: HSR light cone metadata
      parameters:
        - in: path
          name: light_cone_id
          required: true
          schema: { type: integer, example: 23028 }
      responses:
        '200': { description: OK }
  /v1/relic/hsr/set/{set_id}:
    get:
      tags: [Artifact]
      summary: HSR relic set
      parameters:
        - in: path
          name: set_id
          required: true
          schema: { type: integer, example: 314 }
      responses:
        '200': { description: OK }
  /v1/trace/hsr/{avatar_id}:
    get:
      tags: [Character]
      summary: HSR trace tree per character
      parameters:
        - in: path
          name: avatar_id
          required: true
          schema: { type: integer }
      responses:
        '200': { description: OK }