audiobookshelf/docs/controllers/MeController.yaml

components:
  schemas:
    totalTime:
      description: The total time listened in seconds.
      type: integer
      example: 123456
paths:
  /api/me:
    get:
      operationId: getMe
      summary: Get the current user.
      description: Get the current user.
      tags:
        - Me
      responses:
        '200':
            description: Success
            content:
                application/json:
                  schema:
                      $ref: '../objects/entities/User.yaml#/components/schemas/user'
  /api/me/progress/{libraryItemId}/{episodeId}:
    parameters:
      - name: libraryItemId
        in: path
        description: The ID of the library item.
        required: true
        schema:
          $ref: '../objects/LibraryItem.yaml#/components/schemas/libraryItemId'
      - name: episodeId
        in: path
        description: The ID of the episode to get progress for.
        required: false
        schema:
          $ref: '../objects/mediaTypes/Podcast.yaml#/components/schemas/podcastId'
    get:
      operationId: getProgress
      summary: Get the user's progress for a library item.
      description: Get the user's progress for a library item.
      tags:
        - Me
      responses:
        '200':
            description: OK
            content:
                application/json:
                  schema:
                      $ref: '../objects/Media.yaml#/components/schemas/mediaProgress'
        '404':
            description: Not Found
            content:
                html/text:
                  schema:
                      type: string
                      example: Not Found
  /api/me/progress/{mediaId}:
    parameters:
      - name: mediaId
        in: path
        description: The ID of the media progress.
        required: true
        schema:
          $ref: '../objects/Media.yaml#/components/schemas/mediaProgressId'
    get:
      operationId: getProgressById
      summary: Get the user's progress for a media item.
      description: Get the user's progress for a media item.
      tags:
        - Me
      responses:
        '200':
            description: OK
            content:
                application/json:
                  schema:
                      $ref: '../objects/Media.yaml#/components/schemas/mediaProgress'
        '404':
            description: Not Found
            content:
                html/text:
                  schema:
                      type: string
                      example: Not Found
  /api/me/listening-sessions:
    get:
      operationId: getListeningSessions
      summary: Get all listening sessions for the current user.
      description: Get all listening sessions for the current user.
      tags:
        - Me
      parameters:
        - name: itemsPerPage
          in: query
          description: The number of items per page.
          required: true
          schema:
              $ref: '../schemas.yaml#/components/schemas/limit'
        - name: page
          in: query
          description: The page number (zero indexed) to return.
          required: true
          schema:
              $ref: '../schemas.yaml#/components/schemas/page'
      responses:
        '200':
            description: OK
            content:
                application/json:
                  schema:
                      type: object
                      properties:
                          total:
                              $ref: '../schemas.yaml#/components/schemas/total'
                          numPages:
                              description: The number of pages.
                              type: integer
                          itemsPerPage:
                            $ref: '../schemas.yaml#/components/schemas/limit'
                          sessions:
                              type: array
                              items:
                                  $ref: '../objects/entities/PlaybackSession.yaml#/components/schemas/playbackSession'
  /api/me/items-in-progress:
    get:
      operationId: getItemsInProgress
      summary: Get all items in progress for the current user.
      description: Get all items in progress for the current user.
      tags:
        - Me
      parameters:
        - name: limit
          in: query
          description: The number of items to return.
          required: false
          schema:
              $ref: '../schemas.yaml#/components/schemas/limit'
      responses:
        '200':
            description: OK
            content:
                application/json:
                  schema:
                      type: object
                      properties:
                          total:
                              $ref: '../schemas.yaml#/components/schemas/total'
                          numPages:
                              description: The number of pages.
                              type: integer
                          itemsPerPage:
                            $ref: '../schemas.yaml#/components/schemas/limit'
                          items:
                              type: array
                              items:
                                  $ref: '../objects/LibraryItem.yaml#/components/schemas/libraryItemMinified'
  /api/me/listening-stats:
    get:
      operationId: getListeningStats
      summary: Get listening stats for the current user.
      description: Get listening stats for the current user.
      tags:
        - Me
      responses:
        '200':
            description: OK
            content:
                application/json:
                  schema:
                      type: object
                      properties:
                          totalTime:
                              $ref: '#/components/schemas/totalTime'
                          items:
                            type: object
                            description: A list of library items the user has listened to, keyed by their item IDs.
                            additionalProperties:
                              type: object
                              properties:
                                id:
                                  type: string
                                  description: The ID of the library item.
                                timeListening:
                                  type: integer
                                  description: The time (in seconds) the user listened to this library item.
                                mediaMetadata:
                                  oneOf:
                                    - $ref: '../objects/metadata/BookMetadata.yaml#/components/schemas/bookMetadata'
                                    - $ref: '../objects/metadata/PodcastMetadata.yaml#/components/schemas/PodcastMetadata'
                          days:
                            type: object
                            description: A mapping of days to total listening times.
                            additionalProperties:
                              type: integer
                              description: The total time (in seconds) listened to on that day.
                          dayOfWeek:
                            type: object
                            description: A mapping of days of the week to total listening times.
                            additionalProperties:
                              type: integer
                              description: The total time (in seconds) listened to on that day of the week.
                          today:
                            type: integer
                            description: The time (in seconds) the user has listened to library items today.
                          recentSessions:
                            type: array
                            items:
                                $ref: '../objects/entities/PlaybackSession.yaml#/components/schemas/playbackSession'